Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

articles-KMCreateArticle

Updated on September 14, 2021

Pega Knowledge Implementation Guide

Creates an article using the data provided. The system routes the draft article to the New drafts workbasket and processes it through the normal publication workflow. This API allows up to five file attachments with each article, with a maximum file attachment size of 5MB. Limiting the file attachment size helps to control the size of the database and the performance of the application, the search index, general searching, and the response time for users who are accessing file attachments in the user interface or portal. The API also supports the standard file attachment types (.docx, .xlsx, .pptx, and .pdf) and image attachment types (.jpg, .gif, .png, and .svg) that Pega platform supports.

Restricted file types

The following file types are restricted from use in the API import process. You can also add additional file types that you want to restrict from the import process. The ability to restrict additional file types provides flexibility and increased security based on your business needs and security standards. If the application encounters any of the restricted file types, it generates an error code and a corresponding error message.

  • .exe
  • .com
  • .bat
  • .cmd
  • .msi
  • .vb or .vbs
  • .scf
  • .scr
  • .pif
  • .zip
  • .rar

To add additional file types to the restricted list:

  1. Log in to the Pega Knowledge authoring portal.
  2. On the left pane, click Configuration, and then select Article API configuration.
  3. In the Restricted file type field, enter the file type you want to restrict, and then click Add.
  4. Click Save.

Method: POST

Sample endpoint URL

https://<DomainName>/prweb/api/PegaKMREST/articles/KMCreateArticle

Request Header

The Request header should contain Content-Type as a multipart/form-data and boundary that you define with the other data.

Example:

Content-Type: multipart/form-data; boundary=--------abc123

Query parameters

NameTypeDescription
ArticleTitle*stringThe title of the article.
ArticleAbstract*stringThe abstract for the article.
CategoryIDsstringThe Category IDs (for example, TAX-1, TAX-2). If no category is passed, the default is "UNCAT".
ContentType*stringThe Content type (Values: "Authored" or "URL").
ContentURLstringThe URL of a resource if the content type is URL.
ContentBodystringThe Content body (HTML or plain text).
IsInternalContentstringTrue or False. False is the default.
TagsListstringComma-separated tag names.
ArticleLanguage*stringThe master language code of the article.

* Mandatory parameters

Request body

If the content type is set to "Authored", the Request body should contain text for the article body. Because the system sends the request as multipart/form-data, the request body can contain data in the key value format, as shown in the following example:

Example:

Content-Disposition: form-data; name=”Body”

Request parameters

ParameterDescription
ArticleTitleThis is a REST API demo.
Article AbstractThis is a REST API demo.
CategoryIDsTAX-1
ContentTypeAuthored
ContentURL
IsInternalContentFalse
TagsListapi, rest
ArticleLanguageen

Sample request body

The following sample request body contains text for the article body along with an image file in key value format.

File: 0.jpg
Body: this is text for article body
The Http code for the above request body will be as---------------------------------360742209208194055953283
Content-Disposition: form-data; name="file"; filename="0.jpg"
<0.jpg>
--------------------------------------------36-742209208194055953283
Content-Disposition: form-data; name="Body"
this is text for article body

In the above sample code, ----------------------------360742209208194055953283 acts as boundary. File is the key and “0.jpg” is the value. Body is the key and "this is text for article body" is the value.

POST /prweb/PRRRestService/PegaKMREST/articles/KMCreateArticle?
ArticleTitle=This%20is%20rest%20API%20Demo&ArticleAbstract=This%20is%
20rest%20API%20Demo&ContentType=Authored&CategoryIDs=TAX-
1&ContentURL=&IsInternalContent=false&Tags=api&AticleLanguage=en

HTTP/1.1Authorization: Bearer
e3YxfWE3NTNjZTQ0NGM3ODEzMTg2NmFiOTNkNmE3MGE4NTc=

User-Agent: PostmanRuntime/7.26.3Accept: */*Cache-Control: no-
cachePostman-Token: 16347ab3-1e9c-4d1d-aef7-1b654c2fc456Host:
lab5203.lab.pega.comAccept-Encodng: gzip, deflate, brConnection: keep-alive

Content-Type: multipart/form-data; boundary=------------------------------
-544197066538882863805869

Content-Length: 38817 -----------------------54197066538882863805869

Content-Disposition: form-data; name="file";filename="0.jpg"

<0.jpg>
------------------------544197066538882863805869
Content-Disposition: form-data; name="Body"

this is text for article body
----------------------544197066538882863805869

Sample request

{
 
"ArticleAbstract": "",
  "ArticleTitle": "",
  "CategoryIds": "",
  "ContentSourceAuthored": "",
  "ContentSourceURL": "",
  "ContentType": "",
  "KMArticleLanguage": "",
  "KMContentCreationSource": "",
  "tagsList": ""

}

Sample response

{
  "ArticleAbstract": "This is a rest API Demo",
  "ArticleTitle": "This is a rest API Demo",
  "CategoryIds": "TAX-1",
  "ContentSourceAuthored": "this is text for article body",
  "ContentSourceURL": "",
  "ContentType": "Authored",
  "KMArticleLanguage": "en",
  "KMContentCreationSource": "API",
  "pyID": "KC-7006",
  "tagsList": "api"

}

Configuring rate limits to mitigate Denial of Service attachments

You can set the number of articles that can be created via the API for a specific amount of time by configuring the Allowed articles volume and the Time (in minutes) to determine rate limit settings. Note that the combination of the values of these two fields determines the threshold for the rate limit. For example, if you select 1 for time and 1000 for article volume the system will process 1000 article creation requests per minute. If the system receives more than 1000 requests, it generates the following error message: "Rejecting request as number of requests exceeded threshold".

To configure the rate limit:

  1. Log in to the Pega Knowledge authoring portal.
  2. In the left pane, click Configuration, and then select Article API Configuration.
  3. In the Time (in minutes) to determine rate limit field, select the time (in minutes).
  4. In the Allowed articles volume field, select the number of articles that the system can create in the time specified.
  5. Click Save.

Request validation errors

The API request must fulfill certain conditions to avoid errors. The sytem writes any errors to the response message. The following table lists the error conditions and corresponding error messages.
Error conditionError message
The article title is empty."Article title cannot be empty"
The article abstract is empty."Article abstract cannot be empty"
The ContentType is empty or is not equal to "Authored" or "URL""Content type can only be "Authored" or "URL" and is case-sensitive"
The content type is URL and URL is empty, or the content type is set to "Authored" and the content body is empty."For content type "URL", URL field cannot be empty and for content type "Authored", Content body cannot be empty"
The article language is empty. "Article language cannot be empty"
The language does not exist in the system."Language code should exist in the system"
The Category ID does not exist in the system."CategoryID doesn't exist"
An article already exists with the same title."Article title already exists"
The Rate Limiting has been exceeded."Rejecting request s number of requests exceeded threshold"

Attachment validation errors

If there are errors related to attachments, the system creates an article, but the response body will contain the attachment errors along with other details. If more than five attachments are received, only the first five attachments will be attached to the article. You must manually attach the remaining attachments to the article. The following table shows the error conditions and corresponding error messages for file attachments:
Error conditionError message
The file size is greater than 5MB"Failed: File size greater than 5MB"
More than five files are sent"Number of file attachments exceeded the maximum limit of 5 for article "article ID"
Attachment type is restricted"FileType not allowed"

Configuring the virus scan stub

When you configure the CallVirusCheck utility stub, the system calls the utility before uploading any files. If the utility finds a virus, it will not save the file to the database. The system calls the utility for every attachment that is sent using REST API or that is uploaded manually. To handle any viruses that the utility finds, set the VirusCheckStatus parameter in the CallVirusCheck utility with the prefix “Virus”+Message.

Note: The implementation team configures the virus stub utility.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us