Knowledgebase

Overview

The knowledgebase application makes it easy to create articles and questions and organise them into whatever categories you choose. With Knowledgebase you can store and share information and experience across your organisation.

The Knowledgebase application REST API allows you to manage Categories, Articles and Questions in the Knowledgebase application without having to use the Claromentis web front-end, or to build your own applications for your users.

The baseuri for the Knowledgebase REST API through which you interact with knowledgebase resources is:

/intranet/rest/knowledgebase/

There is a tutorial available on using the Knowledgebase API.

Categories

Categories are a way of grouping related articles and questions together. All articles and questions belong to a category.

Categories are not the only way that articles can be organised. It's also possible to add multiple tags to an article to further differentiate them.

The category object

Most of the category endpoints return one or more category objects in JSON format. The category object is defined as follows.

{
    "id": 5,
    "name": "category name",
    "text": "description of category",
    "plain_text": "text version of category description",
    "parent_id": 2,
    "only_experts_answer": 0,
    "created_by": 1,
    "created_date": "20170628095534",
    "modified_by": 1,
    "modified_date": "20170628110156",
    "user_can_create_question": false,
    "user_can_create_article": false,
    "user_can_subscribe": false,
    "user_is_subscribed": false,
    "user_is_subscribed_to_parent": false,
    "parent": {
        "id": 2,
        "name": "parent category name",
        "plain_text": ""
    },
    "subcategories": []
}

The following table describes the entries in the category object.

Get a list of categories

GET /intranet/rest/knowledgebase/categories

Doesn't have any other parameters.

Returns HTTP status code 200 and a JSON-formatted array containing 0 or more category objects.

On failure, returns an HTTP error code.

Get a single category

GET /intranet/rest/knowledgebase/categories/:id

Doesn't have any other parameters

Returns JSON-formatted category object matching :id or a HTTP 404 Not Found error.

Create a new category

POST /intranet/rest/knowledgebase/categories/

A new category is created with a default set of user permissions as follows:

The admin user creating the category has full admin rights over the category, All other users have the rights to view the category and to post articles and questions to it (though not the right to publish the articles they post). These rights can later be adjusted to suit your own needs through the knowledgebase admin panel in Claromentis.

The request body should take this form, some parameters are optional.

{
    "category_name": "My new category name",
    "description": "This is the description of my category",
    "parent_id": 12, 
    "category_experts": [1,2,4], 
    "only_experts_answer": false
}

On success, The newly created category object in JSON-format. On failure, returns an appropriate HTTP error code.

Update a category

PUT /intranet/rest/knowledgebase/categories/:category_id

Update the specific category matching :category_id.

Accepts the same as the POST request but all entries are optional, those not supplied are assumed not to have changed rather than being set to the default.

On success, The updated category object in JSON-format. On failure, returns an appropriate HTTP error code.

Delete a category

DELETE /intranet/rest/knowledgebase/categories/:category_id

Delete the specific category matching :category_id.

Returns 204 code on success, 404 if the category was not found.

Articles

Articles are a great way to organise and share information within your organisation. You can also embed videos in your knowledgebase articles.

The article object

Most of the article endpoints will return one or more article objects, this is defined as follows.

{
    "id": 13,
    "title": "The title of my article",
    "language": "en",
    "category_id": 5,
    "category_name": "Development",
    "cover_filename": null,
    "cover_img": null,
    "cover_thumbnail_img": null,
    "is_endorsed": false,
    "endorsed_by": null,
    "endorsed_date": null,
    "publisher_id": 1,
    "publisher_name": "Claromentis Administrator",
    "plain_text": "The text of the article",
    "article_text": "The text of the article",
    "like_count": 0,
    "comments_enabled": 1,
    "comments_count": 0,
    "comments_enable": 1,
    "embeded_video": false,
    "user_is_subscribed": false,
    "tags": ["mytag1", "mytag2"],
    "created_date": "28 June 2017",
    "modified_date": "28 June 2017"
}

Get a list of articles

GET /intranet/rest/knowledgebase/articles

Optional CGI-style filtering parameters:

• category= :category_id Only return articles from this category
• endorsed_only= :1/0 - Only return endorsed articles
• tag=:tagname Only include results with this tag
• language= :language - Return results in :language - eg en, us, fr, de
• publisher= :publisher_id - Return articles published by user :publisher_id

Returns JSON-formatted array of published article objects or an appropriate HTTP error code. Draft and archived articles are not included.

Get a single article

GET /intranet/rest/knowledgebase/articles/:article_id

Get the specific article matching :article_id.

Returns JSON-formatted article object or an appropriate HTTP error code on failure.

Add a new article

POST /intranet/rest/knowledgebase/articles/

Add a new article.

Accepts:

{
"title": "My knowledgebase article",
"category_id" : 8,
"article_text" : "<p>The text of my article. \"This text has some quotes in it, which need to be escaped\".</p>", 
"publisher_id" : 1, 
"translation" : "en",
"creation_date" : "20170218000000",
"embed_video" : "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/YCcAE2SCQ6k\" frameborder=\"0\" allowfullscreen></iframe>",
"endorsed_by" : 2,
"endorsed_date" : "20170218",
"enable_comments" : true,
"status" : "publish"
}

Returns an error message and HTTP code on failure, or the newly created article object in JSON format on success.

Update an article

PUT /intranet/rest/knowledgebase/articles/:article_id

Update the article :article_id.

Accepts the same options as Adding an article but all fields are optional. Those fields not included are assumed to be unchanged.

Returns an error message and HTTP code on failure, or the updated article object in JSON format on success.

Delete an article

DELETE /intranet/rest/knowledgebase/articles/:article_id

Delete the specific article matching :article_id.

returns 204 code on success, 404 if the article was not found.

Questions

Questions can be asked in a category by users to be answered either by other users or by designated experts in that category. Like articles, questions can be liked and commented upon by other users.

The question object

{
    "id": 10,
    "category_id": 5,
    "category_name": "Category name",
    "title": "Question Title",
    "plain_text": "Text of question",
    "question_text": "Text of question",
    "like_count": 0,
    "comments_count": 0,
    "visits_count": 1,
    "visits_count_text": "1 view",
    "user_is_subscribed": false,
    "created_date": "28 June 2017",
    "created_by": "/people/user/73935872",
    "created_by_title": "Claromentis Administrator",
    "created_by_photo_url": "/appdata/people/1.jpg?1484669928",
    "css_class": "kb-link-disabled",
    "modified_date": "28 June 2017",
    "modified_by": 1
}

Get a list of questions

GET /intranet/rest/knowledgebase/questions

Optional CGI-style filtering parameters:

• category= :category_id (number) Only return questions for this :category_id
• archived= 1 - (boolean) Return archived questions
• unanswered_only= 1 - (boolean) Only return unanswered questions
• tag= :tagname - (string) Only include results with this tag
• language= :language_code - (two-character string) Return results in :language_code - eg en, us, fr, de
• publisher= :publisher_id - (number) Return questions published by user :publisher_id

Returns JSON-formatted array of question objects.

Get a single question

GET /intranet/rest/knowledgebase/questions/:question_id

Get the specific question matching :question_id.

Add a new question

POST /intranet/rest/knowledgebase/questions/

Add a new question to a category.

{
    "title": "Can I ask a question?",
    "text": "<p>lorem ipsum dolor sit amet</p>"
    "category_id": 1
}

Update a question

PUT /intranet/rest/knowledgebase/questions/:question_id

Update the question matching :question_id.

Accepts the same as the POST request but all fields are optional. Missing fields are assumed to be unchanged.

Returns an error message and HTTP response code on failure, or the updated question object in JSON format on success.

Delete a question

DELETE /intranet/rest/knowledgebase/questions/:question_id

Delete the specific question matching :question_id.

returns 204 code on success, 404 if the question was not found.