Knowledge Base API

Knowledge Base (KB) is a handy Automate database with a company-wide scope. This means that one KB is used across all of your projects.

👉 Learn more about Knowledge Base

When creating flows, you can access items stored in Knowledge Base by using Expression language (AEL). There are two ways to do this: using prefix knowledge or using a get() method. You can also check if the item exists by using exists() method. It is possible to use Expression language in Knowledge Base items' values so that they become dynamic.

Accessing Knowledge Base items

KB item's value can be of any data type available in Expression language. If an item is a JSON value, it will be interpreted as either an Array or an Object when accessed.

There are two methods to access KB item's value:

1. Withknowledge prefix

Access KB item's value by using knowledge prefix, the item's key and a dot notation.

Examples

In block's input field: knowledge.someKey.

In block's response field: "The current interest rate is {knowledge.percentage}".

2. With get() method

Access KB item's value using get() method. It allows you to define item's key using dynamic value, eg. knowledge.get(memory.kbItemName).

If you're providing a key literally, use quotation marks (eg. knowledge.get("someKey")). If you're providing a key that is stored as a dynamic value, ommit quotation marks (eg. knowledge.get(memory.kbItemName))

🚧

It is highly recommended not to use dots . in KB items' keys. Use other separators (like _ or -) instead.

Accessing JSON values stored as KB items

KB items recognize JSON as values and interpret them as either an Array or an Object when accessed. This is why you can access their specific properties or use Array or Object methods on them.

Example

In this example, knowledge.people is an Array of Objects.

To print the name stored in the first Object (Paul), we would use such expression:

knowledge.people[0].name.

To print all of the names that aren't equal to "Matthew", we would use such expression:

knowledge.people.map(p => p.name).filter(n => n != "Matthew").join(", ")

👉 Learn more about: Arrays and Objects

Using exists() method to check if KB item by the provided key exists

Check if a KB item with given key exists by using exists() method.

knowledge.exists("someKey") 
// will return true when there is an item with such key in a KB
// will return false when there isn't an item with such key in a KB

Notes on KB item's values syntax

The fact that KB items' values can be interpreted as JSON causes a few edge cases:

• Fully quoted text is a valid JSON and so quotation marks will be stripped. If you need to use quotation marks, then you need to escape them with \, eg. \"String in quotes\".
• Numbers have a type of Number (you can use arithmetics on them). If you want them to be Strings, then use quotation marks, i.e. "55".
• Other valid JSONs, e.g. [1] (an Array with one element: Number 1) will be treated as such. If you want them to be Strings, escape them using quotation marks: "[1]".

Using dynamic values in KB items

It is possible to interpolate dynamic values and other expressions into KB item's value using curly brackets {}.

Example

In this example, knowledge.now will printThe current time is 2022-08-30 08:07., providing the current timestamp as date and time.

Documents

Semantic search method semanticSearch

📘

This method is available since version 244

If this method is not available on your environment please use knowledge.querySimilar

Our system supports semantic search for Documents, making it easy to find the most relevant entries that likely contain answers to customer queries based on the meaning of the search phrase.

You can use the semanticSearch method as shown in the example below:

// Example usage of querySimilar method
// This will return an array of the most relevant items to the user query (up to 10) from "platform_terms" document with at least a 0.75 relevance score.
knowledge.semanticSearch("platform_terms", system.userInput, 10, 0.75)

// Sample result:
[{
  "value" : {
     "Title" : "Section title 1",
     "URL" : "https://example.com/source-url",
     "Content" : "Section content which contains answer to the query"
  },
  "score" : 0.95
}, {
  "value" : {
     "Title" : "Section title 2",
     "URL" : "https://example.com/source-url-2",
     "Content" : "Another section content which contains answer to the query"
  },
  "score" : 0.75
}]


// Another example
knowledge.semanticSearch("platform_terms", "What are platform terms?", 10, 0.75)
// Sample result:
[{
  "value" : {
     "Title" : "Rules",
     "URL" : "https://example.com/terms",
     "Content" : "## Terms and conditions\nBy using our service you agree to share your personal details with Example company"
  },
  "score" : 0.95
}]

// The last two parameters (topK and minimumScore) are optional, so you can also call:
knowledge.semanticSearch("platform_terms", system.userInput)

 

In older versions of Automate, there is an older alternative version of the above method:

knowledge.querySimilar("platform_terms", 
                       system.userInput, 
                       "OPEN_AI_ORGANIZATION_ID", 
                       "OPEN_AI_API_KEY", 
                       10, 
                       0.75)