Support Knowledge with REST API. salesforce Knowledge
Διαφήμιση
Διαφήμιση
Salesforce Knowledge REST APIs Support Knowledge with REST API
Queries are suggested if they exactly match the query string text. The text string must be a prefix within the query; it’s not considered a match if it appears within a word. For example, the text string app would return suggested queries apple banana and banana apples but not pineapple.
If the number of suggestions returned exceeds the limit specified in the request, the end of the response contains a field called hasMoreResults
. Its value is true
if the suggestions returned are only a subset of the suggestions available, and false
otherwise.
If the user’s search query contains quotation marks or wildcards, those symbols are automatically removed from the query string in the
URI.
Support Knowledge with REST API
Knowledge Support REST APIs allow both authorized and guest users to retrieve the user’s visible data categories and their associated articles.
Authenticated users need the
UserProfile.apiEnabled
permission, Knowledge enabled in the organization, read rights on the article type, and any other knowledge specific permission or preference that controls visibility to articles.
Guest users need the
Guest Access to the Support API
preference enabled on the relevant Site, Knowledge enabled in the organization, and read rights on the article type and article channel that controls the visibility for guest users.
Syntax
The root endpoint for all Knowledge support APIs that can be open to guest users.
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
<prefix>/support
HTTP headers
Accept: Optional. Can be either application/json or application/xml .
Input
None
Output
The following resources are related to Knowledge.
:
}
{
"dataCategoryGroups" : "/services/data/vxx.0/support/dataCategoryGroups",
"knowledgeArticles" : "/services/data/vxx.0/support/knowledgeArticles"
Where vxx.0
is the API version you requested.
122
Salesforce Knowledge REST APIs Data Category Groups
IN THIS SECTION:
Get data category groups that are visible to the current user.
Get data category details and the child categories by a given category.
Get a page of online articles for the given language and category through either search or query.
Get all article fields, accessible to the user.
Data Category Groups
Get data category groups that are visible to the current user.
Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/dataCategoryGroups
HTTP headers
Accept: Optional. Can be either application/json
or application/xml
.
Accept-language: Optional. Language to translate the categories. Any ISO-639 language abbreviation, and an ISO-3166 country code subtag in the HTTP Accept-Language header. Only one language accepted. If no language specified, the non-translated labels are returned.
Input: string sObjectName
: Required.
KnowledgeArticleVersion
only.
boolean topCategoriesOnly : Optional. Defaults to true
• True returns only the top level categories.
• False returns the entire tree.
Note: All the input parameters are case-sensitive.
Output:
A list of the active data category groups that are visible to the current user in the site context. Returns id, name, label, and their top level categories or the entire data category group tree that are visible to the current user. The labels must be translated to the given language if they are available.
• Data Category Group List
123
Salesforce Knowledge REST APIs Data Category Groups
This payload lists the active root Data Category Groups that can be used in other requests to return the data categories and articles related to it.
{
"categoryGroups": [
}
Note: Returns only the active groups that are associated to the given entity (by sObjectName ). Only
KnowledgeArticleVersion
is supported.
• Data Category Group
This represents an individual data category group, and its root category.
{
"name": String, // the unique name of the category group
"label": String, // returns the translated version if it is available
"objectUsage" : String, // currently only "KnowledgeArticleVersion" is available.
"topCategories": [
}
• Data Category Summary
This provides a summary of data category information. The Summary and Detail responses share common properties, with the goal of providing only as much information as is necessary from associated resources.
{
"name": String, // the unique name of the category
"label": String, // returns the translated version if it is available
"url": URL, // the url points to the data category detail API
"childCategories": [ Data Category Summary, ....] // null if topCategoriesOnly is true
}
Note: The URL property is a pre-calculated path to the unique resource representing this data category, in this case it is
Example
Input
/services/data/v38.0/support/dataCategoryGroups?sObjectName=KnowledgeArticleVersion
Output
{
"categoryGroups" : [ {
"label" : "Doc",
"name" : "Doc",
"objectUsage" : "KnowledgeArticleVersion",
"topCategories" : [ {
"childCategories" : null,
"label" : "All",
"name" : "All",
"url" :
124
Salesforce Knowledge REST APIs Data Category Detail
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion"
} ]
}, {
"label" : "Manual",
"name" : "Manual",
"objectUsage" : "KnowledgeArticleVersion",
"topCategories" : [ {
"childCategories" : null,
"label" : "All",
"name" : "All",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Manual/dataCategories/All?sObjectName=KnowledgeArticleVersion"
}
} ]
} ]
Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. Use the language code format used in Which Languages Does Salesforce Support?
.
Only the user’s visible data categories are returned. A user might be able to see several sub trees in the category group, therefore, the top categories that are visible to the user in each group are returned.
Data Category Detail
Get data category details and the child categories by a given category.
Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/dataCategoryGroups/[group]/dataCategories/[category]
HTTP headers
Accept: Optional. Can be either application/json
or application/xml
.
Accept-language: Optional. Language to translate the categories. Any ISO-639 language abbreviation, and an ISO-3166 country code subtag in the HTTP Accept-Language header. Only one language accepted. If no language specified, the non-translated labels are returned.
125
Salesforce Knowledge REST APIs
Input: string sObjectName
: Required.
KnowledgeArticleVersion
only.
Output:
Details of the category and a list of child categories (name, label, etc.).
• Data Category Detail
Used for situations where the hierarchical representation of data categories is important. The child property contains a list of child data categories.
{
"name": String, // the unique name of the category
"label": String, // returns the translated version if it is available
"url": URL,
"childCategories": [
Data Category Summary , ....],
}
Note: If the category isn’t visible to the current user the return is empty.
Example
Input
/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion
Output
{
"childCategories" : [ {
"childCategories" : null,
"label" : "Help",
"name" : "Help",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/Help?sObjectName=KnowledgeArticleVersion"
}, {
"childCategories" : null,
"label" : "QA",
"name" : "QA",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/QA?sObjectName=KnowledgeArticleVersion"
} ],
"label" : "All",
"name" : "All",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion"
}
Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. Use the language code format used in Which Languages Does Salesforce Support?
.
126
Data Category Detail
Salesforce Knowledge REST APIs Articles List
Articles List
Get a page of online articles for the given language and category through either search or query.
Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/knowledgeArticles
HTTP headers
Accept: Optional. Can be either application/json
or application/xml
.
Accept-language: Required. The article must be an active language in the user’s organization
• If the language code isn’t valid, an error message is returned: “The language code is not valid or not supported by Knowledge.”
• If the language code is valid, but not supported by Knowledge, then an error message is returned: “Invalid language code. Check that the language is included in your Knowledge language settings."
Input: string q : Optional, Performs an SOSL search. If the query string is null, empty, or not given, an SOQL query runs.
string channel
: Optional, defaults to user’s context. For information on channel values, see
.
• App: Visible in the internal Salesforce Knowledge application
• Pkb: Visible in the public knowledge base
• Csp: Visible in the Customer Portal
• Prm: Visible in the Partner Portal string categories
in map json format
{“group1”:”category1”,”group2”:”category2”,...} )
Optional, defaults to None. Category group must be unique in each group:category pair, otherwise you get
ARGUMENT_OBJECT_PARSE_ERROR
.
string queryMethod values are: AT, BELOW, ABOVE, ABOVE_OR_BELOW . Only valid when categories are specified, defaults to ABOVE_OR_BELOW.
string sort : Optional, a sortable field name LastPublishedDate, CreatedDate, Title, ViewScore . Defaults to LastPublishedDate for query and relevance for search.
Note: When sorting on ViewScore it is only available for query, not search, and no pagination is supported. You only get one page of results.
string order : Optional, either ASC or DESC, defaults to DESC. Valid only when sort is valid.
integer pageSize
: Optional, defaults to 20. Valid range 1 to 100.
integer pageNumber : Optional, defaults to 1.
127
Salesforce Knowledge REST APIs Articles List
Output:
A page of online articles in the given language and category visible to the current user.
• Article Page
A page of articles. The individual entries are article summaries so the size can be kept at a minimum.
{
“articles”: [
, … ], // list of articles
“currentPageUrl”: URL, // the article list API with current page number
“nextPageUrl”: URL, // the article list API with next page number, which can be null if there are no more articles.
“pageNumber”: Int // the current page number, starting at 1.
}
Note: The API supports paging. Each page of responses includes a URL to its page, as well as the URL to the next page of articles.
• Article Summary
A summary of an article used in a list of article responses. It shares similar properties to the Article Detail representation, as one is a superset of the other.
{
“id”: Id, // articleId
“articleNumber”: String,
“title”: String,
“summary”: String,
“url”: URL, // to the Article Detail API
“viewCount”: Int, // view count in the interested channel
“viewScore”: double (in xxx.xxxx precision), // view score in the interested channel.
“upVoteCount”: int, // up vote count in the interested channel.
“downVoteCount”: int, // down vote count in the interested channel.
“lastPublishedDate”: Date // last publish date in ISO8601 format
“categoryGroups”: [
The “url” property always points to the
resource endpoint. For information on valid channel values, see the
• Data Category Group
An individual data category group, its root category, and a list of selected data categories in the group.
{
}
“groupName”: String, // the unique name of the category group
“groupLabel”: String, // returns the translated version
“selectedCategories”: [
, … ]
• Data Category Summary
Provides a summary of data category information. The Summary and Detail responses share common properties.
{
“categoryName”: String, // the unique name of the category
“categoryLabel”: String, // returns the translated version, per the API language specified
128
Salesforce Knowledge REST APIs Articles List
“url”: String // returns the url for the DataCategory REST API.
}
Note: The outputs of Data Category Group and Data Category Summary in Article List API are different from the Data
Category Groups API.
Example
Input
/services/data/v38.0/support/knowledgeArticles?sort=ViewScore&channel=Pkb&pageSize=3
HTTP Headers:
Content-Type: application/json; charset=UTF-8
Accept: application/json
Accept-Language: en-US
Output
{
"articles" : [ {
"articleNumber" : "000001002",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000000BCAQ",
"lastPublishedDate" : "2015-02-25T02:07:18Z",
"summary" : "With this online Chinese input tool, you can type Chinese characters through your web browser without installing any Chinese input software in your system.
The Chinese online input tool uses the popular Pin Yin input method. It is a fast and convenient tool to input Chinese on English OS environments.",
"title" : "Long text test",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000BCAQ",
"viewCount" : 4,
"viewScore" : 100.0
}, {
"articleNumber" : "000001004",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000000LCAQ",
"lastPublishedDate" : "2016-06-21T21:11:02Z",
"summary" : "The number of characters required for complete coverage of all these languages' needs cannot fit in the 256-character code space of 8-bit character encodings, requiring at least a 16-bit fixed width encoding or multi-byte variable-length encodings.
\r\n\r\nAlthough CJK encodings have common character sets, the encodings often used to represent them have been developed separately by different East Asian governments and software companies, and are mutually incompatible. Unicode has attempted, with some controversy, to unify the character sets in a process known as Han unification.\r\n\r\nCJK character encodings should consist minimally of Han characters p",
"title" : "Test Images",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ",
"viewCount" : 0,
"viewScore" : 0.0
}, {
129
Salesforce Knowledge REST APIs Articles Details
"articleNumber" : "000001012",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000006GCAQ",
"lastPublishedDate" : "2016-06-21T21:10:48Z",
"summary" : null,
"title" : "Test Draft 2",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000006GCAQ",
"viewCount" : 0,
"viewScore" : 0.0
} ],
"currentPageUrl" :
"/services/data/v38.0/support/knowledgeArticles?channel=Pkb&pageSize=3&sort=ViewScore",
"nextPageUrl" : null,
}
"pageNumber" : 1
Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. The Custom File
Field is not supported because it returns a link to a binary stream. Use the language code format used in Which Languages Does Salesforce
Support?
.
Valid
channel
Values
• When using the options string channel , where the matching articles are visible, the following values are valid.
–
App
–Visible in the internal Salesforce Knowledge application
– Pkb –Visible in the public knowledge base
– Csp –Visible in the Customer Portal
–
Prm
–Visible in the Partner Portal
• If channel
isn’t specified, the default value is determined by the type of user.
– Pkb for a guest user
–
Csp
for a Customer Portal user
– Prm for a Partner Portal user
– App for any other type of user
• If channel is specified, the specified value may be used to retrieve articles.
– For guest, Customer Portal, and Partner Portal users, if the specified channel is other than the channel accessible to the user, an error is returned.
– For all users other than guest, Customer Portal, and Partner Portal users, the specified channel value is used.
Articles Details
Get all article fields, accessible to the user.
130
Salesforce Knowledge REST APIs Articles Details
Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/knowledgeArticles/{articleId}
HTTP headers
Accept: Optional. Can be either application/json or application/xml .
Accept-language: Required. The article must be an active language in the user’s organization
• If the language code isn’t valid, an error message is returned: “The language code is not valid or not supported by Knowledge.”
• If the language code is valid, but not supported by Knowledge, then an error message is returned: “Invalid language code. Check that the language is included in your Knowledge language settings."
Input: string channel
: Optional, defaults to user’s context. For information on channel values, see
.
• App: Visible in the internal Salesforce Knowledge application
• Pkb: Visible in the public knowledge base
• Csp: Visible in the Customer Portal
• Prm: Visible in the Partner Portal boolean updateViewStat
: Optional, defaults to true. If true, API updates the view count in the given channel as well as the total view count.
Output:
The detailed fields of the article, if the article is online and visible to the current user.
• Article Detail
Full detail of an article, with complete metadata and layout-driven fields used for display of an article. It includes all the same
properties as an Article Summary
representation.
{
"id": Id, // articleId,
"articleNumber": String,
"title": String,
"summary": String,
"url": URL,
"versionNumber": Int,
"createdDate": Date, // in ISO8601 format
"createdBy":
on page 132,
"lastModifiedDate": Date, // in ISO8601 format
"lastModifiedBy":
on page 132,
"lastPublishedDate": Date, // in ISO8601 format
"layoutItems": [
// standard and custom fields visible
131
Salesforce Knowledge REST APIs Articles Details to the user, sorted based on the layouts of the article type.
"categories": [
"appUpVoteCount": Int,
"cspUpVoteCount": Int,
"prmUpVoteCount": Int,
"pkbUpVoteCount": Int,
"appDownVoteCount": Int,
"cspDownVoteCount": Int,
"prmDownVoteCount": Int,
"pkbDownVoteCount": Int,
"allViewCount": Int,
"appViewCount": Int,
"cspViewCount": Int,
"prmViewCount": Int,
"pkbViewCount": Int,
"allViewScore": Double,
"appViewScore": Double,
"cspViewScore": Double,
"prmViewScore": Double,
"pkbViewScore": Double
}
• User Summary
{
"id": String
"isActive": boolean // true/false
"userName": String // login name
"firstName": String
"lastName": String
"email": String
"url": String // to the chatter user detail url:
/services/data/xx.x/chatter/users/{userId}, for guest user, it will return null.
}
• Article Field
An individual field of article information, which is listed in an Article Detail
in the order required by the administrator’s layout.
{
"type": Enum,
"name": String,
"label": String,
"value": String,
}
// see the Notes
// field name
// label
Example
Input
/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ
HTTP Headers:
Content-Type: application/json; charset=UTF-8
132
Salesforce Knowledge REST APIs
Accept: application/json
Accept-Language: en-US
Output
{
"allViewCount" : 17,
"allViewScore" : 100.0,
"appDownVoteCount" : 0,
"appUpVoteCount" : 0,
"appViewCount" : 17,
"appViewScore" : 100.0,
"articleNumber" : "000001004",
"categoryGroups" : [ ],
"createdBy" : {
"email" : "[email protected]",
"firstName" : "Test",
"id" : "005xx000001SvoMAAS",
"isActive" : true,
"lastName" : "User",
"url" : "/services/data/v38.0/chatter/users/005xx000001SvoMAAS",
"userName" : "[email protected]"
},
"createdDate" : "2016-06-21T21:10:54Z",
"cspDownVoteCount" : 0,
"cspUpVoteCount" : 0,
"cspViewCount" : 0,
"cspViewScore" : 0.0,
"id" : "kA0xx000000000LCAQ",
"lastModifiedBy" : {
"email" : "[email protected]",
"firstName" : "Test",
"id" : "005xx000001SvoMAAS",
"isActive" : true,
"lastName" : "User",
"url" : "/services/data/v38.0/chatter/users/005xx000001SvoMAAS",
"userName" : "[email protected]"
},
"lastModifiedDate" : "2016-06-21T21:11:02Z",
"lastPublishedDate" : "2016-06-21T21:11:02Z",
"layoutItems" : [ {
"label" : "Out of Date",
"name" : "IsOutOfDate",
"type" : "CHECKBOX",
"value" : "false"
}, {
"label" : "sample",
"name" : "sample",
"type" : "PICK_LIST",
"value" : null
}, {
"label" : "Language",
"name" : "Language",
"type" : "PICK_LIST",
"value" : "en_US"
133
Articles Details
Salesforce Knowledge REST APIs Articles Details
}, {
"label" : "MyNumber",
"name" : "MyNumber",
"type" : "NUMBER",
"value" : null
}, {
"label" : "My File",
"name" : "My_File",
"type" : "FILE",
"value" : null
} ],
"pkbDownVoteCount" : 0,
"pkbUpVoteCount" : 0,
"pkbViewCount" : 0,
"pkbViewScore" : 0.0,
"prmDownVoteCount" : 0,
"prmUpVoteCount" : 0,
"prmViewCount" : 0,
"prmViewScore" : 0.0,
"summary" : "The number of characters required for complete coverage of all these languages' needs cannot fit in the 256-character code space of 8-bit character encodings, requiring at least a 16-bit fixed width encoding or multi-byte variable-length encodings.
\r\n\r\nAlthough CJK encodings have common character sets, the encodings often used to represent them have been developed separately by different East Asian governments and software companies, and are mutually incompatible. Unicode has attempted, with some controversy, to unify the character sets in a process known as Han unification.\r\n\r\nCJK character encodings should consist minimally of Han characters p",
"title" : "Test Images",
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ",
"versionNumber" : 7
}
Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. The Custom File
Field is not supported because it returns a link to a binary stream. Use the language code format used in Which Languages Does Salesforce
Support?
.
A lookup custom field is visible to guest users depending on the lookup entity type. For example, User is visible, but Case and Account are not visible. Following standard fields are not visible to a guest user, even if they are in the layout:
• archivedBy
• isLatestVersion
• translationCompletedDate
• translationImportedDate
• translationExportedDate
• versionNumber
• visibleInInternalApp
• visibleInPKB
• visibleToCustomer
• visbileToPartner
134
Salesforce Knowledge REST APIs Articles Details
Valid
channel
Values
• When using the options string channel , where the matching articles are visible, the following values are valid.
–
App
–Visible in the internal Salesforce Knowledge application
–
Pkb
–Visible in the public knowledge base
– Csp –Visible in the Customer Portal
–
Prm
–Visible in the Partner Portal
• If channel
isn’t specified, the default value is determined by the type of user.
– Pkb for a guest user
– Csp for a Customer Portal user
–
Prm
for a Partner Portal user
– App for any other type of user
• If channel is specified, the specified value may be used to retrieve articles.
– For guest, Customer Portal, and Partner Portal users, if the specified channel is other than the channel accessible to the user, an error is returned.
– For all users other than guest, Customer Portal, and Partner Portal users, the specified channel value is used.
135
CHAPTER 4 Salesforce Knowledge Metadata API
In this chapter ...
•
•
•
•
•
•
•
You can manage articles, page layouts, and data categories with the Metadata API.
Use Metadata API to retrieve, deploy, create, update or delete customization information, such as custom object definitions and page layouts, for your organization. This API is intended for managing customizations and for building tools that can manage the metadata model, not the data itself.
For generic Metadata API information see the Metadata API Developer Guide .
136
Λήψη
Δημόσιος σύνδεσμος ενημερώθηκε
Ο δημόσιος σύνδεσμος για τη συνομιλία σας ενημερώθηκε. You may view and manage your chat links after registration here.
Δημόσιος σύνδεσμος εγγράφου
Διαφήμιση
