Skip to main content

Knowledge base

A knowledge base is a collection of articles. The collection is structured in a tree where one article is a node that can have multiple sub-articles (child nodes).

The first node in the tree is the root node. This is the entry point for all the top-level articles. The root node will not be visible outside ITX, but inside it will contain some configuration options and the name of the knowledge base to easily identify it. When retrieved, the root node will also be the only node that contains the tree configuration object, which we will come back to.

All other nodes are directly corresponding to an article. It will contain a title and an optional body. When not supplying a body, the node can be used just for grouping other nodes together by making them children of the node. This can be useful for categorization.

TREE---------------------------+
|  ROOT_NODE                   |
|  |__TOP_ARTICLE_1            |
|  |__TOP_ARTICLE_2            |
|  |  |__SUB_ARTICLE_2_1       |
|  |  |  |__SUB_ARTICLE_2_1_1  |
|  |  |__SUB_ARTICLE_2_2       |
|  |__TOP_ARTICLE_3            |
+------------------------------+

Creating knowledge base​

POST <endpoint>/rest/document/content

When creating ane knowledge base you will initially create a root node, which will in turn create a tree in background a connect that node to the tree.

Notes​

The translations property is a map structure of translations that is used both for title and content. To make the translation available (e.g. visible to users of the FAQ widget) the root node must add the laguage to languages within the tree's config. The fallbackLanguage is used for cases where the requsted language is not available.

1. Create new root node and tree​

The root node is the root of all document and is used for configuring global options and naming the entire knowledge base for identifying it in ITX.

To create a root node, you have to not supply the tree field, and the response will generate a new tree field with a corresponding id (cotrId). This field is the id of the knowledge base.

{
  "name": {
    "translations": {
      "en": {
        "language": "en",
        "translatedText": "My knowledge base"
      }
    }
  },
  "tree": {
    "config": {
      "documentNodeTreeConfig": {
        "languages": ["en"],
        "fallbackLanguage": "en"
      }
    }
  },
  "active": true
}

2. Creating a document node​

A document node is a document that contains a name and optional content. Here you need to supply the tree id (cotrId) and a parent node, which in our case is the root, to place it under.

Empty node (used for grouping)​

{
  "name": {
    "translations": {
      "en": {
        "language": "en",
        "translatedText": "My empty node"
      }
    }
  },
  "parent": {
    "ctnoId": 1234
  },
  "tree": {
    "cotrId": 1234,
    "corporationGroup": {
      "cogrId": 1
    }
  },
  "active": true
}

Content node under empty node​

{
  "name": {
    "translations": {
      "en": {
        "language": "en",
        "translatedText": "My article"
      }
    }
  },
  "nodeContentList": [
    {
      "sort": 0,
      "text": {
        "translations": {
          "en": {
            "language": "en",
            "translatedText": "<p>This is my entire article</p>"
          }
        }
      },
      "active": true,
      "contentType": "HTML"
    }
  ],
  "parent": {
    "ctnoId": 2345
  },
  "tree": {
    "cotrId": 1234,
    "corporationGroup": {
      "cogrId": 1
    }
  },
  "active": true
}

3. Updating a document node​

To update a document node, you have to retrieve the full node first, change the values you want and send it as request to the same endpoint

Retrieve existing knowledge bases​

GET <endpoint>/document/nodes

Retrieve one document​

To retrieve one document supply ctnoId. The following will retrive document with id 5, with all the translations, as well as the root node's tree config if the node is a root node

?ctnoId=5&getNodeContent=true&getAllTextTranslations=true&getRootNodeTreeConfig=true

Retrieve structure​

Supplying the cotrId will retrieve all documents in the tree. The following will retrieve all nodes in tree with id 3, with the title in all languages, but without the content of each document.

?cotrId=3&getNodeContent=false&getAllTextTranslations=true

Images​

Images can be embedded as normal HTML <img> tags in the content.

Upload image​

To upload images to ITX and use those set the src attribute to a base64 format. When content is retrieved with uploaded images, these will appear as image tags with an itx-src attribute <img itx-src="*********">. This is the format that should be used for any subsequent saves. For displaying, they can be replaced it <img src="<endpoint>/rest/document/file?id=*********">.