Introduction

As a company or organization with a strong, online presence, it’s likely that you’ve invested heavily in a tool to manage your knowledge and content. This knowledge management system (KMS) or content management system (CMS) helps keep your content organized for easy updates. You’ve set up the system, trained your users on it, and socialized processes to make sure the content is complete, accurate, and follows your branding rules. So, it's naturally important to you that KnowledgeAI™ connect with this system, so you can leverage your vast knowledge and content in your Conversational AI solution. The good news is that all this is possible.

If your KMS or CMS has a public API for retrieving knowledge articles, you can integrate it with KnowledgeAI using LivePerson’s Integration Hub (iHub) application. iHub embeds Workato, a leading third-party enterprise automation platform, inside Conversational Cloud. What’s so special about Workato? Power. Flexibility. And a no-code/low-code approach to integration and automation.

In iHub, you can create a Workato recipe to sync the content in your external KMS/CMS into KnowledgeAI. Sync the content using a trigger, such as an automated schedule, or sync it on demand whenever you require it.

Terms and concepts

Internal knowledge bases

At LivePerson (and in this documentation), we classify a knowledge base that you integrate with an external KMS/CMS via a Workato integration in iHub as an “internal knowledge base.” This is because the content is stored internally within KnowledgeAI.

In the knowledge base’s settings, you’ll see “internal knowledge base” as the Knowledge base type.

The Knowledge base type setting in the knowledge base's settings

The term “internal knowledge base” isn’t used elsewhere in the UI. However, because there is also such a thing as an external knowledge base, we use the term to make the documentation simpler and communication faster and easier.

Be aware that you can also create an internal knowledge base by importing Web pages, PDFs, a Google sheet, or a CSV file. Or, by adding articles manually within KnowledgeAI. These too are internal knowledge bases because the content is stored internally within KnowledgeAI.

Projects

In Workato, a project is a container for a set of related workflows, recipes, and automation tasks. Create a project to store assets related to your KnowledgeAI integration.

Example projects

LivePerson recommends that you create one project to store all your KnowledgeAI-related assets. But it’s up to you. Organize things however is easiest for you.

Recipes

In Workato, a recipe is a pre-built automation workflow that connects different applications and systems to perform specific tasks or processes. It consists of triggers that initiate the workflow, actions that define what should happen, and conditions or logic to control the flow of data and information between connected applications.

Example recipe

Recipes simplify integration and automation by providing a structured way to create and manage workflows without the need for extensive coding or development expertise.

At a high level, to integrate your KMS/CMS with KnowledgeAI, you must create a recipe that:

  1. Retrieves the content from your KMS/CMS
  2. Maps it to our LivePerson data schema for articles
  3. Imports the content into a knowledge base in KnowledgeAI

Templates and customization

LivePerson offers both generic and vendor-specific templates to make integration with KnowledgeAI easier.

Example templates

Take advantage of a template; don’t start from scratch. That said, feel free to customize and extend the recipe however you need. For example, you might want to alter it to send an email to an email address whenever a job fails.

To help you quickly understand how a template works, all of the templates are self-documenting. That is, they include comments that describe the various triggers and actions.

Watch the video

Check out our short video on integrating a Zendesk KMS in under 15 minutes.


While this video walks through the process of integrating a Zendesk KMS in specific, most (if not all steps) apply regardless of the vendor and KMS.

Integrate the KMS or CMS

Prerequisite steps

New to embedded Workato in the Integration Hub (iHub)? Get acquainted by reviewing the general user guide in our Knowledge Center.

Step 1: In KnowledgeAI, create the knowledge base

  1. Open KnowledgeAI, and click Add knowledge base in the upper-right corner.
  2. Fill out the form, and select “External KMS/CMS” for Content source.

    The Add Knowledge Base form, with a callout to the Content Source setting

  3. Click Save.
  4. In the window that appears, use the Copy icon to copy your account ID, the knowledge base ID, and the client secret to the clipboard. (The client secret is used by Workato to authenticate with KnowledgeAI.) Paste the info somewhere for easy reference. You'll need it later in this process.

    The window that contains the info to copy: Account ID, Knowledge base ID, and client secret

  5. Click Go to iHub.

Step 2: In iHub, activate embedded Workato

This is a step that you only perform once in iHub. It creates the Workato tenant for your account within the mult-tenancy Workato architecture. It also creates an admin user for your account. More users are created on the fly as needed. Learn more about all of this in the iHub Workato user guide in our Knowledge Center.

  1. On the left navigation bar, click Manage > Integration Hub.
  2. Click Workflows in the menu in the upper-left corner.
  3. Click Activate to activate our embedded Workato workspace inside Conversational Cloud.

    The Activate button

  4. Review and accept the terms of service by clicking the available checkbox. Then click Accept.

    The window on which to review and accept terms

  5. Click Enter Workato.

    The Enter Workato button

Step 3: In iHub, create a project

LivePerson recommends that you create one project to store all your KnowledgeAI-related assets. But it’s up to you. Organize things however is easiest for you.

  1. Under Workflows, select Assets.
  2. Beside PROJECTS on the left, click the “ + “ sign.
  3. Enter a name and description for the project.

    The form to fill out to create a project

  4. Click Create project.

Step 5: In iHub, create the Workato recipe

In this step, you create the Workato recipe that imports content from your external KMS/CMS into the knowledge base that you created in KnowledgeAI.

  1. Click Community Library on the menu bar.
  2. Enter the search term "liveperson" to search for the KnowledgeAI recipe templates.
  3. Select "LivePerson Knowledge Articles Import."

    Example templates

  4. Select the recipe you need.

    Example templates

  5. Click Use this recipe in the upper-right corner.

    The Use this recipe button

  6. Select the project in which to copy the recipe, and click Copy and save.

    The Copy and save button

  7. Click Customize recipe to begin customization.

    The Customize recipe button

    Customizing a recipe

  8. Before you get too far along with customization, change the recipe name to something descriptive and meaningful to your brand.

    The recipe name field

Key customization points

The comments in the elements in the recipe guide you through customization. However, the following are the key customization points. Vendor-specific recipes vary slightly.

Trigger - Specify a schedule

Below TRIGGER, click the “Trigger on a custom schedule” element. Edit it to specify the schedule on which to run the recipe.

Specifying the trigger for running the recipe

Action - Get the content from the KMS/CMS

Below ACTIONS, locate and click the “Select an app and action” element (or similarly named element depending on the template). Edit the element:

  1. Select the application (KMS or CMS) to connect to.
  2. Select the action that retrieves the content from the KMS or CMS.
  3. Create the new connection to the KMS or CMS.
  4. Configure any extra settings as required.

Configuring the element that retrieves the content from the CMS

Action - Map the content to the LivePerson article schema

Locate and click the “Add items to articles list” element (or similarly named element depending on the template). In the element, map the KMS/CMS article schema to the KnowledgeAI fields provided.

Configuring the element that maps the retrieved article content to the KnowledgeAI article schema

Action - Add the content to the knowledge base in KnowledgeAI

Locate and click the “Add all articles to LivePerson KnowledgeAI” element (or similarly named element depending on the template). This element binds the recipe to the content source in KnowledgeAI.

A callout to the element named Add all articles to LivePerson KAI

Edit the element to fill in all required info.

On the Connection tab, you’ll use the info that you recorded earlier when you created the knowledge base in KnowledgeAI. This takes care of:

  • Brand/Account ID
  • Knowledge Base ID
  • Client Secret

Also on the Connection tab, specify the Workato recipe ID. You can get this from the URL in the browser window, like so:

A callout to the recipe ID that's in the URL in the browser window

Still in the same element, switch to the Setup tab:

A partial view of the Setup tab

On the Setup tab, there are three settings to take care of:

  • deleteUnrepresentedArticlesFromKB: If you set this to "Yes," articles that exist in the knowledge base in KnowledgeAI—but are not represented (included) in the current import request from the external CMS/KMS—are deleted from the knowledge base in KnowledgeAI. So adds, updates, and deletes can all occur in the knowledge base. If you set this to "No," then those unrepresented articles remain, as is, in the knowledge base in KnowledgeAI.
  • workatoUserId: To set this field, first click inside of it, and then get the ID from the recipe data like so:

    A short animation that shows the user clicking the field, scrolling to the top of the Recipe Data window that opens, expanding Properties, and selecting the user ID

  • jobId: You set the job ID just like you set Workato recipe ID: Click in the field, and then get it from the properties in the recipe data.

A view of the Job ID field in the Properties in the Recipe Data

The API enables all new articles, so ensure the content is suitable before the recipe is run.

Step 6: In iHub, test and debug the recipe

In the upper-right corner, click Test recipe to test the recipe.

The test performs an actual run of the recipe, so this results in updates to the knowledge base in KnowledgeAI.

The Test Recipe button

If you don’t get a success message, debug the recipe and try again after fixing it.

A success message after testing the recipe

Step 7: In KnowledgeAI, verify the articles

As a final step, go to the knowledge base in KnowledgeAI, and verify the articles are there and look as expected.

Payloads and status codes

Request payload

{
    "articles": [
        {
            "title": "title",
            "summary": "summary",
            "deleteRequest": "true/false"
            //....
        }
    ],
    "pruneNonIncludedArticles": "true/false",
    "kbId" : "<<kbId>>",
    "correlationId" : "<<workatoUserId::recipeId>>",
    "jobId" : "<<recipe-jobId>>"
}

pruneNonIncludedArticles is a reference to the deleteUnrepresentedArticlesFromKB value/setting, described earlier.

Success response payload

{
   "success": true,
   "errorCode": "200",
   "successResult": {
       "status": "STARTED",
       "correlationId" : "xxxxxxxxx"
}
}

Response statuses

There is no response body for non-200 status codes.

Status code Description
200 Success response
400 Bad request; request validation failures
401 Not authorized to access the resource
404 Requested response not found; knowledge base data source is not found for the given ID; no content source of KMS type found for a given knowledge base ID; invalid recipe ID/Workato user ID/job ID
429 Too many requests
500 Internal server error

Start or stop the recipe's schedule

To start a recipe so that it runs on its schedule, click the corresponding action button on the Sources page in KnowledgeAI:

The action button for starting the recipe to run on its schedule

You stop a recipe from running on its schedule in a similar way:

The action button for stopping the recipe from running on its schedule

Manually run the recipe

You can run a recipe on demand at any time. To do so, click the recipe name link on the Sources page in the knowledge base in KnowledgeAI. This takes you directly to the recipe in iHub, where you can do this.

The recipe name link on the Sources page, which takes you directly to iHub where you can run the recipe on demand

In iHub, the option to run the recipe manually (click "Test recipe" not "Start recipe") is available in several prominent spots, like this one below:

The Start recipe button

Delete content

On the Sources page in the knowledge base in KnowledgeAI, there's a Delete action available for deleting an individual content source.

The Delete button for an individual content source on the Sources page within a knowledge base

Deleting a content source does two things:

  • Deletes the articles associated with the recipe from the knowledge base.
  • Disassociates the recipe from the knowledge base. That is, the content source is removed from the list on the page.

However, the recipe remains available in iHub.

On the other hand, if you first delete a recipe in iHub, you'll still see the content source (the recipe) listed on the Sources page within the knowledge base in KnowledgeAI. And you'll still see a corresponding Delete action available there too. In this case, it works the same: It deletes the associated articles and disassociates the recipe (which doesn't exist in iHub anymore).

Since two different applications are involved (KnowledgeAI and iHub), when performing deletes, ensure things are aligned across the applications as you expect. And take care because the operations aren't reversible.

Reporting

To check the results of jobs, use the Sources page in the knowledge base in KnowledgeAI:

The Sources page showing that the last recipe run was successful from a job status standpoint and a content status standpoint

If you encounter errors, scroll way to the right, and click the View errors link. This opens a window with info on the errors.

The Sources page showing the Content Status as Errors and a callout to the View Errors link

Finally, from the Sources page, you can quickly get to the recipe in iHub by clicking the recipe name. More detailed reporting on jobs is available in iHub.

Best practices

  • Solutions: Keep it simple, not complicated.

    • Strive for a “one recipe per knowledge base” approach.
    • Don’t use one recipe to sync from multiple external KMS/CMS.

    KnowledgeAI can run only one recipe per knowledge base at a time. Set each recipe’s schedule accordingly.

  • Connections: Never reuse an existing connection. If you copy (clone) a recipe, in the copy always create and configure a new connection. This is necessary because the recipe ID is bound in the connection.
  • Importing articles into KnowledgeAI: Always use the available “Add all articles to LivePerson KnowledgeAI” connector element; don't set up a custom HTTP request.
  • Monitoring: Check the Sources page in KnowledgeAI on a regular basis to verify that your jobs are running successfully. It’s also a best practice to regularly verify that the content in KnowledgeAI looks as expected.
  • Minor changes: Go ahead and make these directly in the relevant recipe.
  • Major changes: To make these, we recommend that you clone the recipe, make the changes in the copy, and then replace the original recipe after testing has proven to be successful.

Troubleshooting

Within a recipe, use the Jobs page to drill down to errors that occurred:

The Jobs page

On the Jobs page, click the error to navigate to the problematic element.

Then use the Input, Error, and Debug panels to help you understand and solve the problem.

The Input panel

If you're discussing an issue with us, provide us with the correlationId that was received in the response. We'll use that to check our internal logs.

FAQs

Can I further customize the recipe?

Certainly. Validation, pre-processing, post-processing is all up to you. Configure this as you require.

Is the client secret shared across knowledge bases?

No, a client secret isn’t shared across knowledge bases. However, it is shared across all content sources (recipes) within the same knowledge base.

I've lost the client secret for a knowledge base. How do I retrieve it?

On the knowledge base's Sources page, click Add recipe in the upper-right corner. This opens a window where you can copy it again.

Can I use KnowledgeAI to manually add articles to the internal knowledge base?

Yes, you can. But be aware that those articles aren’t updated when the recipe runs.

The impact to manually added articles depends on the recipe’s configuration. For example, if you intend to add articles manually, it's likely that you'll want to set deleteUnrepresentedArticlesFromKB (discussed above) to "No" so that such articles aren't deleted when a sync operation occurs.

Can I add multiple content sources in a single knowledge base?

Yes, you can. But in this case, in all of the recipes, set deleteUnrepresentedArticlesFromKb (discussed above) to “No” in the connector element that imports the articles into KnowledgeAI. Otherwise, articles from one source will be deleted by the recipe run for another source.

Can I use a single recipe across multiple knowledge bases?

You can, but we don't recommend this. Strive for a “one recipe per knowledge base” approach.

If you proceed and use a single recipe across multiple knowledge bases, the recipe must have multiple connections, each of which must use a different client secret.

My KMS/CMS isn't listed by vendor name. It says, "Custom." Why is that?

Your KMS/CMS is still supported. It's just that we haven't yet added the vendor name to our back-end list of known names. Contact your LivePerson representative to get it added.

A callout to the Provider name column

I don't see my recipes listed on the Sources page of the knowledge base. Why is that?

If you have a knowledge base that you integrated with a CMS/KMS prior to our February 2024 release, you won’t initially see its associated recipes listed on the Sources page. To resolve this:

  1. In Conversational Cloud, navigate to iHub, and open the recipe.
  2. If the recipe is running, stop it.
  3. In the recipe, navigate to the “Add all articles to LivePerson KnowledgeAI” element, select it, and click Edit.
  4. In the panel on the right, click Connection, and add a new connection. (Deleting the existing connection is optional, but we recommend you do so.) Make sure all required fields in the new connection have info, including but not limited to Workato recipe ID, which is a new field as of our February 2024 release. (For help with setting these fields, see the discussion farther above on this element.) Then click Connect.
  5. Switch from the Connection tab to the Setup tab. Make sure all required fields have info, including but not limited to Workato user ID and Job ID. These are new fields too as of our February 2024 release.

Once the new connection is established, the recipes are shown on the Sources page.