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 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.
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.
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:
- Retrieves the content from your KMS/CMS
- Maps it to our LivePerson data schema for articles
- 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.
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.
https://player.vimeo.com/video/909112305
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
Step 1: In KnowledgeAI, create the knowledge base
- Open KnowledgeAI, and click Add knowledge base in the upper-right corner.
- Fill out the form, and select “External KMS/CMS” for Content source.
- Click Save.
- 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.
- 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.
- On the left navigation bar, click Manage > Integration Hub.
- Click Workflows in the menu in the upper-left corner.
- Click Activate to activate our embedded Workato workspace inside Conversational Cloud.
- Review and accept the terms of service by clicking the available checkbox. Then click Accept.
- Click Enter Workato.
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.
- Under Workflows, select Assets.
- Beside PROJECTS on the left, click the “ + “ sign.
- Enter a name and description for the project.
- 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.
- Click Community Library on the menu bar.
- Enter the search term "liveperson" to search for the KnowledgeAI recipe templates.
- Select "LivePerson Knowledge Articles Import."
- Select the recipe you need.
- Click Use this recipe in the upper-right corner.
- Select the project in which to copy the recipe, and click Copy and save.
- Click Customize recipe to begin customization.
- Before you get too far along with customization, change the recipe name to something descriptive and meaningful to your brand.
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.
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:
- Select the application (KMS or CMS) to connect to.
- Select the action that retrieves the content from the KMS or CMS.
- Create the new connection to the KMS or CMS.
- Configure any extra settings as required.
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.
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.
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:
Still in the same element, switch to 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:
- 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.
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.
If you don’t get a success message, debug the recipe and try again after fixing it.
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:
You stop a recipe from running on its schedule in a similar way:
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.
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:
Delete content
On the Sources page in the knowledge base in KnowledgeAI, there's a Delete action available for deleting an individual content source.
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:
If you encounter errors, scroll way to the right, and click the View errors link. This opens a window with info on the errors.
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
- KnowledgeAI can run only one recipe per knowledge base at a time. Set each recipe’s schedule accordingly.
- Strive for a “one recipe per knowledge base” approach.
- Don’t use one recipe to sync from multiple external KMS/CMS.
- 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:
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.
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.
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:
- In Conversational Cloud, navigate to iHub, and open the recipe.
- If the recipe is running, stop it.
- In the recipe, navigate to the “Add all articles to LivePerson KnowledgeAI” element, select it, and click Edit.
- 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.
- 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.
Ready to move on to the next capability? Click here to proceed.
