Introduction

The data schema used by your CMS differs from that used by LivePerson KnowledgeAI, so mapping the content from the former to the latter is a required step in setting up an external knowledge base. This involves defining a Jolt transformation spec to transform the data that's retrieved from the CMS. Jolt is an open-source, JSON-to-JSON transformation library.

If you’re using a popular CMS vendor (e.g., Salesforce or Zendesk), LivePerson provides a default, vendor-specific, Jolt spec. You’ll need to adjust the default specification accordingly if you’ve customized the CMS’ data schema. On the other hand, if you’re using a CMS vendor for which no default spec is available, you’ll need to write one from scratch. In either case, use the examples that follow as a guide.

Jolt provides several, out-of-the-box transforms that you can use when writing the spec. The Shift transform in particular does most of the heavy work when it comes to the transform; it specifies how the input JSON should be “shifted around” to make the output JSON. All of the examples that follow use the Shift transform.

The Shift transform supports very simple to very complex data transformations, powered by wildcards: *, &, @, $, and #. The examples that follow cover what's needed for transformation to the LivePerson KnowledgeAI article schema. To learn about more complex use cases, see the Jolt test samples, which are documented by the Jolt team.

Supported LivePerson attributes

See this section for the list of supported LivePerson attributes when content mapping.

Reading the examples

Terminology:

LHS = left-hand side = the input JSON tree
RHS = right-hand side = the output JSON tree

Examples — Map article suggestions/answers (external KB without LivePerson AI)

Example 1

Input JSON

{
  "results": [
    {
      "url": "https://livepersonkb.zendesk.com/api/v2/help_center/en-us/articles/360048237271-How-to-Reset-password.json",
      "title": "How to Reset password",
      "label_names": [
        "Profile"
      ],
      "body": "<p>Go to login page, and click on \"forgot password\" button below password field, and follow the instructions to receive the password reset email. </p>"
    },
    {
      "url": "https://livepersonkb.zendesk.com/api/v2/help_center/en-us/articles/360048237271-How-to-Reset-password.json",
      "title": "Account Information",
      "label_names": [
        "Account"
      ],
      "body": "<p>For account information, go to Settings → Account → Basic Information.</p>"
    }
  ]
}

Transformation specification

[
  {
    "operation": "shift",
    "spec": {
      "results": {
        "*": {
          "title": "[&1].title",
          "label_names": "[&1].tags",
          "body": "[&1].summary",
          "url": "[&1].contentURL"
        }
      }
    }
  }
]

Transformed output

[ {
  "title" : "How to Reset password",
  "tags" : [ "Profile" ],
  "summary" : "<p>Go to login page, and click on \"forgot password\" button below password field, and follow the instructions to receive the password reset email. </p>",
  "contentURL" : "https://livepersonkb.zendesk.com/api/v2/help_center/en-us/articles/360048237271-How-to-Reset-password.json"
}, {
  "title" : "Account Information",
  "tags" : [ "Account" ],
  "summary" : "<p>For account information, go to Settings → Account → Basic Information.</p>",
  "contentURL" : "https://livepersonkb.zendesk.com/api/v2/help_center/en-us/articles/360048237271-How-to-Reset-password.json"
} ]

Example 2

Input JSON

{
  "searchRecords": [
    {
      "attributes": {
        "type": "KnowledgeArticleVersion",
        "url": "/services/data/v42.0/sobjects/KnowledgeArticleVersion/ka0050000004EEFAA2"
      },
      "Title": "How to reset password",
      "Summary": "To reset password, click on the link provided below password field on the logon page.",
      "KnowledgeArticleId": "kA0050000004EA3CAM"
    },
    {
      "attributes": {
        "type": "KnowledgeArticleVersion",
        "url": "/services/data/v42.0/sobjects/KnowledgeArticleVersion/ka0050000004F5YAAU"
      },
      "Title": "How to Login",
      "Summary": "Go to login page mentioned in the developer documentation, and enter your credentials.",
      "KnowledgeArticleId": "kA0050000004F1HCAU"
    }
  ]
}

Transformation specification

[
  {
    "operation": "shift",
    "spec": {
      "searchRecords": {
        "*": {
          "KnowledgeArticleId": "[&1].externalId",
          "Title": "[&1].title",
          "Summary": "[&1].summary",
          "attributes": {
            "url": "[&2].contentURL"
          }
        }
      }
    }
  }
]

“[&2].contentURL” is used on the RHS because the “searchRecords” array index is two levels up from “url”, i.e., url → attributes → searchRecords index.

Transformed output

[ {
  "externalId" : "kA0050000004EA3CAM",
  "title" : "How to reset password",
  "summary" : "To reset password, click on the link provided below password field on the logon page.",
  "contentURL" : "/services/data/v42.0/sobjects/KnowledgeArticleVersion/ka0050000004EEFAA2"
}, {
  "externalId" : "kA0050000004F1HCAU",
  "title" : "How to Login",
  "summary" : "Go to login page mentioned in the developer documentation, and enter your credentials.",
  "contentURL" : "/services/data/v42.0/sobjects/KnowledgeArticleVersion/ka0050000004F5YAAU"
} ]