Quick win 15. Salesforce Knowledge Rest APIs

Salesforce Knowledge Rest APIs

SF knowledge rest apis comes in 4 different flavours (Types) based on the polymorphic nature of the data model and each different type (as below) has set of actions contained in it

1. sObject Type Knowledge__kav API : To create, query knowledge articles

• /services/data/v54.0/sobjects/Knowledge__kav/

2. KnowledgeManagement type API : To Manage articles, versions and it’s translations, you would use this class of api

• /services/data/v54.0/knowledgeManagement

3. Support Knowledge API : To query Article list, article details and articles based on the Data category they are associated with, you would use this, example using, Data Category Groups, Data Category Detail, Articles List, Articles Details

• /services/data/v54.0/support/knowledgeArticles

4. Invocable Actions API : a service to mass publish knowledge articles , generally you would use this api & its actions to manage your articles and article versions.

• /services/data/v54.0/actions/standard/publishKnowledgeArticles

For the SOAP version of the API, please check this

Small note: You can use these APIs in a simple 1.1 rest api calls or you can also put them together in a composite resource, we will talk about this also but there are some limitations from the above list which the composite resource supports, please keep this in mind

Now, lets look at some of the examples to see how we can create an article, assign them to data categories and publish them programatically (using API)

1. Create a knowledge article in draft status

note: you cannot set the “publishstatus” in the payload (data object) using this call
POST
/services/data/v54.0/sobjects/Knowledge__kav/
{
“summary”:”Summary for the Article 1",
“title”:”hello world”,
“urlName”:”hello-world1"
}

You can also set the ‘recordtypeid’ above if you are in salesforce lightning.

Small note: You can not use/ set the publish status in the json data object as it does not support at the moment and articles can only be created in draft status (default)

Raw Response

HTTP/1.1 201 Created
Date: Sun, 14 Aug 2022 10:02:14 GMT
Set-Cookie: CookieConsentPolicy=0:1; path=/; expires=Mon, 14-Aug-2023 10:02:14 GMT; Max-Age=31536000
Set-Cookie: LSKey-c$CookieConsentPolicy=0:1; path=/; expires=Mon, 14-Aug-2023 10:02:14 GMT; Max-Age=31536000
Location: /services/data/v54.0/sobjects/Knowledge__kav/ka15e0000011oBdAAI
Content-Type: application/json;charset=UTF-8
Vary: Accept-Encoding
Content-Encoding: gzip
Transfer-Encoding: chunked
{
  "id" : "ka15e0000011oBdAAI",
  "success" : true,
  "errors" : [ ]
}

2. Assign / link them to data categories

where “Knowledge__DataCategorySelection” is the object which stores the article relation with its data categories. Each assigned data category is mapped as record in this Object :

POST
/services/data/v54.0/sobjects/Knowledge__DataCategorySelection
{
“ParentId”:”ka15e0000011oBiAAI”,
“DataCategoryGroupName”:”Product”,
“DataCategoryName”:”XP80"
}

Raw Response

HTTP/1.1 201 Created
Date: Sun, 14 Aug 2022 10:23:05 GMT
Set-Cookie: CookieConsentPolicy=0:1; path=/; expires=Mon, 14-Aug-2023 10:23:05 GMT; Max-Age=31536000
Location: /services/data/v54.0/sobjects/Knowledge__DataCategorySelection/02o5e00000224tfAAA
Content-Type: application/json;charset=UTF-8
Vary: Accept-Encoding
Content-Encoding: gzip
Transfer-Encoding: chunked
{
  "id" : "02o5e00000224tfAAA",
  "success" : true,
  "errors" : [ ]
}

3. Publish the articles programatically

where “publishKnowledgeArticles” is the resource available from the 4th type of knowledge resource which is invocable API actions, the “articleVersionIdlist” parameter from below accepts Knowledge article version Ids created from create api in a comma separated format

POST
/services/data/v54.0/actions/standard/publishKnowledgeArticles

{
“inputs” : [
{
“articleVersionIdList” : [ “ka15e0000011oBiAAI” ],
“pubAction” : “PUBLISH_ARTICLE”
}
]
}

Raw Response

HTTP/1.1 200 OK
Date: Sun, 14 Aug 2022 10:36:07 GMT
Set-Cookie: CookieConsentPolicy=0:1; path=/; expires=Mon, 14-Aug-2023 10:36:07 GMT; Max-Age=31536000
Content-Type: application/json;charset=UTF-8
Vary: Accept-Encoding
Content-Encoding: gzip
Transfer-Encoding: chunked
[ {
  "actionName" : "publishKnowledgeArticles",
  "errors" : null,
  "isSuccess" : true,
  "outputValues" : {
    "ka15e0000011oBi" : "Success"
  }
 } 
]

There is also another resource available which you can use to publish an article, I am using it in composite resource in order to combine with other API operations, but this is just an example

other option. Using Manage Knowledge APIs(resource Type 2 from above list)
{
“allOrNone” : true,
“collateSubrequests”: true,
“compositeRequest” : [

{
“method” : “PATCH”,
“url” : “/services/data/v25.0/knowledgeManagement/articleVersions/masterVersions/ka15e0000011oBsAAI”,
“referenceId” : “refkmid”,
“body” : { “publishStatus”:”Online”}
}
]
}

Now, Let’s see how we can combine operations from above in a Composite way for following reasons :

• 1. reduce number of API calls and execute “ series of multiple REST API requests into 1 Single POST request " and reduce the number of round trips between client and server (this contributes naturally to application’s performance)
• 2. To bulkify operations meaning passing / sending more number of records (collections) as part of 1 API call or fewer api calls.

Question: You might wonder why we are talking about composite resource here, Yes — I didn’t share the context earlier.

What happens normally in an enterprise business model is you don’t not have just one system responsible for knowledge articles creation and At times there comes the need to integrate various types content (FAQ, Manuals, instructions etc.) from multiple sources and bring to Salesforce as a single repository for operational usage (e.g for your Sales / support agents or customers etc.)

And this is where using a composite resource at your integration layer (dell Boomi / mulesoft) who are orchestrating the data/ integration flow is helpful to reduce many api calls, hence the need for composite resource so that they don’t have to repeat the process again and again.

Approach 1:

Here we will use the combination of Composite 1) (sobject Tree) resource in combination with 2) Knowledge Invokable action from above, thereby creating multiple records with 1 or fewer API call(s) to process all records together (given : maximum limit 200 total records across all trees / per callout)

The idea here is to bulkify and process multiple records together in just one or few API calls rather than serially processing per record with ↔ 1 API call, what it means is we map all the records from an external system in to the request payload and pass it over as part of the same api call avoiding the need to make as many api calls as number of records

You can even create structure for process parent- child relationship (as we need in our case with knowledge article version and data categories) in the sample payload and send multiple records keeping in mind we don’t go over the maximum 200 total records limit per call.

Concluding again., here is the benefit:

1. As said already, we can create multiple records of same type knowledge articles (knowledge__kav) k1, k2, k3 together in 1 api call which avoid jumping back and forth and avoid multiple resource calls.

• + You can create child records (nested parent-child) for knowledge__kav with data categories as well k1+ dc1, k2 +dc2, k3+dc3 (where dc means data category and k1: Knowledge article) combining 2 operations in 1 plus offering ability to do it for multiple records.

For all records from external system, create a single big payload (remember max: 200 records) containing few to many records and do both operations,

1. create article and assign them data categories using 1 single api call

2. Mass publish them with 1 api call

Method : POST
/services/data/v54.0/composite/tree/Knowledge__kav

{
"records" :[{
    "attributes" : {"type" : "Knowledge__kav", "referenceId" : "ref1"},
     "summary":"Summary for the Article",
     "title":"hello world 13",
     "urlName":"hello-world13",   
     "DataCategorySelections" : {
      "records" : [{
         "attributes" : {"type" : "Knowledge__DataCategorySelection", "referenceId" : "ref2"},
          "DataCategoryGroupName":"Product",
           "DataCategoryName":"XP80"
         },{
         "attributes" : {"type" : "Knowledge__DataCategorySelection", "referenceId" : "ref3"},
           "DataCategoryGroupName":"Product",
           "DataCategoryName":"X21"
         }]
      }
    },{
    "attributes" : {"type" : "Knowledge__kav", "referenceId" : "ref4"},
     "summary":"Summary for the Article ",
     "title":"hello world 14",
     "urlName":"hello-world14",
     "DataCategorySelections" : {
      "records" : [{
        "attributes" : {"type" : "Knowledge__DataCategorySelection", "referenceId" : "ref5"},
          "DataCategoryGroupName":"Product",
          "DataCategoryName":"XP80"
        }]
      }   
  }]
}

Raw Response

HTTP/1.1 201 Created
Date: Sun, 14 Aug 2022 19:36:36 GMT
Content-Encoding: gzip
Transfer-Encoding: chunked
{
  "hasErrors" : false,
  "results" : [ {
    "referenceId" : "ref1",
    "id" : "ka15e0000011oCbAAI"
  }, {
    "referenceId" : "ref4",
    "id" : "ka15e0000011oCcAAI"
  }, {
    "referenceId" : "ref2",
    "id" : "02o5e00000224utAAA"
  }, {
    "referenceId" : "ref3",
    "id" : "02o5e00000224uuAAA"
  }, {
    "referenceId" : "ref5",
    "id" : "02o5e00000224uxAAA"
  } ]
}

After this they need to collect the knowledge articles versions id from the response above and pass it into the method we already talked about for mass publishing (vXX.x/actions/standard/publishKnowledgeArticles/”) to publish them all together

Last Point, in order to use the composite resource, prior check the sobject and operations it supports as there are some minor limitations to it but not blockers:). An example “invocable Action API” to mass publish articles is NOT supported in composite resource but only in batch composite type resource , here are the details

Reference links

Knowledge APIs
https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/resources_knowledge_support.htm

Composite API
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite.htm

Knowledge Data model
https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_guidelines_knowledge.htm

That’s all for today, hope you enjoyed and learned something.

Cheers Mohit