Entities Articles

How to create data source entities

Use data source entities in Bold360 AI to turn your data into smart conversations.

Make sure your widget is set to conversational. Learn more here.

In this example, we have a list of mobile phones and we want to create a bot that recommends users the best mobile devices based on their needs. We are going to set up a data source entity based on this list of mobile phones and then create an article that uses this entity.

Create the list of mobile phones in a CSV file.
A sample CSV file is attached at the end of this article. Learn more about the different data source options and requirements in this article.
In the AI Console, go to Knowledge > Entities.
Choose (Create Entity).
Select data source entity for entity type.
Provide a name and optionally a description for the entity.
The entity name can contain letters, numbers and underscores. Spaces are not allowed.

You can use the description to give the entity a more meaningful name or description that helps you identify it later.

Example: Name your entity MOBILE_PHONES.
Fill out the Data Source URL field.
You can select the CSV file from your local computer and upload it to Bold360 AI' secure server or you can upload the file to a file hosting service like OneDrive and enter its URL here.

Note: If you provide a link to the file's location, make sure it's publicly accessible.
See What are the data source URL options? for more options.
Set the response type to CSV.
Choose LOAD.
Result: The properties table is now loaded. Properties are the columns that are available in the data source file.
Fill out the Properties table.
See What are the property options for data source entities? and How do life cycle options work? to learn more about the options.

Example:

You should decide what questions the bot should ask the end users to offer the best possible recommendation about phones. In this example, the bot asks questions about brand, price range, and camera quality.
Optional: Define fallback messages.
See What are fallback messages? to learn more.

Example: For this example, we enter Unfortunately, there's no mobile device that matches your preferences. for no results and set up a carousel to be displayed with the image, the brand and model, and the price if there are multiple results based on the customer's responses.
Save your changes.
Now go to Knowledge > Articles.
Create a new article or open an existing one and add the entity in the article's body.
In the article's body, create the final response of the bot: this is what the bot responds when there is a single mobile device to recommend. The response should use the entity to present the details of the selected mobile device. To insert an entity, you can either choose or enter [[ in the text editor and have a drop-down of all entities displayed. Once you add an entity to the response, the entity is automatically added to the article. You can expand the entity to see the questions that the bot may ask the user and adjust them to fit the article if needed.

Note: You can drag-and-drop entities in the Article Editor to control the order of the questions in the conversation.
Example: Intent: I want to buy a mobile phone

Body: ?
Publish the article.

You can now see the conversation in action in your widget ? just enter I want to buy a mobile phone.

Important: The bot doesn't always ask all the questions we set in the entity. It can automatically identify when there is no need to ask a question, for example, when there is only one possible result left. In addition, the order of the questions might differ as the bot automatically chooses the order based on what it estimates as the fastest way to get to a possible answer.

What property options are available for custom entities?

Property options in Bold360 AI enable you to customize entities.

Table 1. Property options for custom entities
Option name	Description
Life cycle	The Life Cycle field above the properties table sets the life cycle for the entire entity. You can also set a life cycle for each property. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Name	The expression used to identify the property and add to articles. The property name can contain letters, numbers and underscores. Spaces are not allowed.
Detect	Specifies the type of input expected from the user, like text, date or number. Validation is completed based on the selection here. For example, if email is selected, the user is expected to enter an email address, otherwise they receive an error. If you choose Date, customers can use a calendar to select the date:
Bot Query	The question the bot asks to receive the input from the user.
Error Message	The error message displayed to the user when they provide an input that is not valid. You can also set the number of times the error message is to be displayed, that is, the number of chances you give the user to provide the correct format. After that the user receives the fallback message. For example, you have a property where Detect is set to Email, the bot query is What's your email address? and the error message is Please provide an email address. which is set to be displayed 3 times. When the user fails to provide an email address for the fourth time, the fallback message or article is displayed if it is set up. Note: Validation is not possible for text-type properties, so you can't enable error messages for such properties.
Life cycle	The Life Cycle field of the property sets the life cycle for the specific property. You can also set a life cycle for the entity. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.

What are the property options for data source entities?

Property options in Bold360 AI enable you to customize entities.

The options listed here are available in the Properties table of data source entites. Some of them you can find under (More options).

Table 1. Property options for data source entities
Option name	Description
Life cycle	The Life Cycle field above the properties table sets the life cycle for the entire entity. You can also set a life cycle for each property. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Expose?	Sets the visibility of this property in a conversation.
Key	Displays the header names as they are in the data source.
Name	The expression used to identify the property and add to articles. The property name can contain letters, numbers and underscores. Spaces are not allowed.
Detect	Controls whether the property is visible in a conversation.
Query	The question the bot asks to receive the input from the user.
Life cycle	The Life Cycle field of the property sets the life cycle for the specific property. You can also set a life cycle for the entity. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Split by	A syntax value such as a comma or a vertical bar that is used to separate multiple values in a CSV cell or in the value associated with a JSON key.
Auto Spelling	When selected, the customer's answer doesn't have to be an exact match to a value in a CSV cell or a value associated with a JSON key.
Is Shared	You can share the selected property with another entity. For example, if you define color in your phone and tablet entities, then you can share the color values across entities. In this case, when the customer selects a phone color that doesn't exist in the phone entity but exists in the tablet entity which is shared, then the bot will know it is a color and present the message defined in the entity for no results.
Autocomplete	When selected, customers are offered autocomplete, or type-ahead options as they enter the entity value.
Use Quick Option	The customer can choose from the values that a specific CSV column or JSON key contains. For example, if the CSV contains Apple, Samsung, and Google in the Brand column for a list of mobile phones, these options are displayed as buttons to the customer. See How to use quick options in a conversational article to learn more.
Parent property	You can set up a dependency between two properties of the same entity. For example, the parent property of Cities can be Country. When the customer is asked about these two properties, the following happens: The bot asks the question for the parent property first. For example, What country are you located in? and then Which city do you reside in?. If the Country property is either asked again or deleted, the City property is also deleted, that is, the child property behaves in the same way as the parent property.

How to create API-based entities

Entities in Bold360 AI enable you to turn your data into smart chatbot conversations.

Note: The steps described in this article require web developer knowledge.

To set up an API-based entity you need a custom entity to collect data from the customer for the API, a data source entity with the API as its data source that uses the custom entity and an article you use these entities in. In this example, we have an API for data about concert tickets and we want to create a bot that the customer can ask about the tickets that they already booked.

Create a custom entity.

You create this entity to collect the data required for the API. In this example, we're asking for the customer's email address to display their booked concert tickets.

Example:

Entity name: TicketDeails

Entity description: Collect the customer's email address

*Table 1. Property table of TicketDetails*
Name	Detect	Bot Query	ErrorMessage	Life Cycle
Email	Email	What's your email address?	Please enter a valid email address.	Persistent

Create a data source entity with the API as its data source.
1. Choose (Create Entity).
2. Select custom entity for entity type.
3. Provide a name and optionally a description for your entity.
  The entity name can contain letters, numbers and underscores. Spaces are not allowed.
  
  You can use the description to give your entity a more meaningful name or description that helps you identify it later.
  
  Example:
  
  Entity Name: TicketsByName
  
  Entity Description: Get a list of tickets by email address
4. In the Data Source URL field, enter the URL of the API and add the property of the custom entity you created in Step 1.
  Example: https://api.example.com/v1/tickets/[[TicketDetails.Email]]
  
  Result: The custom entity is listed as a dependent entity under the Properties Table. See What are dependent entities? to learn more.
5. Change Response Type to JSON.
6. Choose LOAD.
7. On the set parameters samples dialog enter a sample email address and choose LOAD.
  This way the system knows what a valid response looks like.
  
  Result: The Properties table is automatically filled with the keys that come from the API.
8. Define display settings.
  Display settings are available for arrays. See What are the display settings for API-based entites? or more information.
9. Save the entity.
Create an article that uses these entities.
1. Go to Knowledge > Articles.
2. Create a new article or open an existing one and add the entity in the article's body.
  Example: Intent: What tickets do I have reserved?
  
  Body: ?You have the following tickets reserved: [[TicketsByEmail.TicketsByEmail_ARRAY]]
3. Publish the article.

You can now see the conversation in action in your conversational widget.

What are dependent entities?

Dependent entities are entities used in other entities.

When you have an entity with an API as data source, you need to set up a custom entity that collects the information from the user and and include this custom entity in the API-based data source entity to pass it on to the API. Dependent entities provide a better understanding of what properties compose the entity.

To add dependent entities, do the following:

In the AI Console, go to Knowledge > Entities.
Select an existing entity or create a new one.
Choose click URL inputs next to Data Source URL.
Add the entity you want to use.
You can add an entity on the Parameters,Headers or Bodytab, depending on where it's needed. The entity should be added in [[Entity_Name.Property.Name]].

The dependent entities are listed under the Properties Table.

How do life cycle options work?

The life cycle of an entity in Digital DX defines the period during which the bot remembers the user's answer.

You can define a life cycle for the entity as well as for each property of the entity. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole.

Table 1. Entity life cycle options
Life cycle option	Description
Persistent	The bot remembers the user's answers for the duration of the session, that is, until the user closes the browser.
Topic	The bot remembers the user's answers as long as the articles returned to the user's questions contain the entity. So as soon as the user asks the bot for an article that does not use the entity, the bot deletes the user's answer from its memory.
Intent	The bot remembers the user's answer as long as the user is in the same intent. So as soon as the user asks the bot something else, the bot deletes the user's answer from its memory even if the answer to the user's next question contains the same entity.
Statement	The bot remembers the user's answer until another question is asked from the user. For example, if the bot asks two questions, like What is your first name? and What is your email address?, the bot forgets the user's first name before the second question is asked.

What are the data source URL options?

Use these options when providing a link to a file or an API link in the Data Source URL field of a data source entity in Bold360 AI.

When creating a data source entity, you can either upload a CSV or a JSON file from your local drive or add a URL to such a file or provide the URL of an API as data source.

Entities support two types of HTTP methods to integrate an external URL: POST and GET. You can select a method from the drop-down next to the Data Source URL field.
The following options are also available for data source URLs:

URL inputs which enable you to add header and body content
Interval settings where you can set the refresh interval for how often the cached version of the file is to be refreshed
Download file to get a local copy of the file

URL Inputs

To integrate an external data source, you may need to use specific parameters, headers or include specific data in the body of the request when you send it to the server that stores the data files.

When you select (URL Inputs), you have the option to add parameters, headers and a body in case of POST requests. It is possible to include another entity as a parameter, in the header and in the body in which case this entity is listed as a dependent entity under the Properties table. See How to create API-based entities to learn more.

Headers

In several cases, POST requests require specific headers to be sent to the server. When testing a POST request, the tool you're using might automatically add certain default headers without even showing them to you. Make sure you add all headers in the entity configuration.

Body

In the body you can add content. The body of an HTTP request supports different formats for sending content. The format you should use depends on what the receiving server expects. In the AI Console, POST requests in entities support raw format only.

How can I use entities in user search?

You can map words of a phrasing that are values in an entity to the relevant property of the entity you are using in the article.

Using this example, you could add the phrasing I want to buy a Samsung phone and map Samsung to the MOBILE_PHONES.BRAND to make sure the bot won't ask the question about brand when the user already antered their preference.

In the Bold360 AI platform, go to Knowledge > Articles.
Open an article or create a new one.
Example: In our example, we have the I want to buy a mobile phone article.
Add a phrasing that contains a property value of the entity you use in the article.
Example: Add I want to buy a Samsung phone.

Result: You'll see that the word that is a property value is highlighted in blue.
Select the word that is the property value and choose the entity property it belongs to.
Publish the article.

Now when the user uses the phrasing you added, the bot won't ask them the question the related question. In our example, the bot will skip the question about mobile brand as it already knows the user is looking to buy a Samsung one.

What are the display settings for API-based entites?

Display settings are available for arrays in API-based data source entities.

Choose for an array in the Properties table of your API-based data source entity to set up the following options:

Display results in a carousel
Display results as quick buttons
Display a message when there are no results

What are system entities?

You can use built-in, or system entities even without defining your own ones. These Entities let you define the following:

NUM - Stores the numeric value that the user enters.
EMAIL - The answer displays the email address that the user entered as part of the intent.
DATE - User can either select a date from a date picker or type a date in MM/DD/YYYY format. The answer displays that value in MM/DD/YY format.
DATE_TODAY -
DATE_TODAY_DISPLAY -
DURATION - Converts weeks, days, hours, and minutes into number of days.
DATE_RANGE -
DATE_RANGE_PAST -
DATE_RANGE_FUTURE -
LOCATION - Returns the user's geolocation (latitude and longitude coordinates).

What are entities?

Entities in Bold360 AI enable you to turn your data into smart chatbot conversations.

Tip: Check out this video to see entity configuration in action.

Entities serve as a database for the information that the conversational bot needs to answer your customers' questions. You set up an entity with a data source and provide different questions the conversational bot will ask the customer about the same set of data. For example, you have a data source for mobile phones and you want to create a conversational bot that recommends your customers the best mobile devices based on their needs. Your data source contains information about the brand, the model, the price, the screen size and so on of the mobile phones available. In the entity, you can set up questions about these bits of information, like Any specific brand you're looking for? and What is the price range?. The customer answers these questions and the conversational bot provides the best fit or fits based on their answers.

With entities, you can provide a smart conversational experience to your customers:

If the customer provides an answer to a question that the conversational bot hasn't asked yet, it won't ask that question. For example, if someone is looking for an iPhone with 64GB memory, the bot will skip the question about memory type and potentially the one about phone type as well.
The conversational bot presents the questions in the most effective way to ensure the customer has to provide the least number of answers to find the result. So regardless of the order of the questions in the entity, the conversational bot rearranges the questions in the most logical way.
When a question has one answer only, the bot simply skips that question and does not present it to the customer. For example, if there is only one Samsung phone with a 7" screen, the bot doesn't ask the customer about either the camera or the memory of the phone, but displays the result immediately.

Bold360 AI supports the following types of entities:

Data source entities where the data comes from
- a CSV or a JSON file or
- an external data source through an API
Custom entities that you can use
- to collect information from your customers in an interactive way
- an auxiliary for API-based data source entities as they help collect the information required for the API and then trigger the API itself

Conversation entity verification

As a content manager, you can create conversations that verify answers that end-users provided and to prevent any typos or other human errors. To do that, create a new step in the process of API-based entities that will do the following:

Summarize the data the user has provided
Present the data to the user in the widget
Enable the user to change the data if needed or to confirm.

How do data source entities work?

Use data source entities in Bold360 AI to turn your data into smart conversations.

Data source entities can be based on a CSV or a JSON file or can retrieve data from an external data source through an API. In terms of the data source, you have the following options:

Upload the file from your local drive
Upload the file to a file hosting service like OneDrive and add its URL to the entity
Specify the URL of an API

See What are the data source URL options? to learn more.

Makes sure the CSV or JSON file you use with entities meet the following requirements:

The file is valid, for example, the CSV file contains no unescaped commas. Use a validator tool to check.
If you provide a link to the file's location, make sure it's publicly accessible.
The file is structured in a way that
- Each bot query corresponds to a column
- Each response corresponds to a row or a part of it
- Columns are divided into two parts: bot queries and answers.

See this article to learn how to set up an entity with a CSV data source.

How to use custom entities

Use custom entities in Bold360 AI to gather information from your customers and use it to offer a personalized experience.

Make sure your widget is set to conversational. Learn more here.

You can also use custom entities as an auxiliary for API-based data source entities as they help collect the information required for the API and then trigger the API itself.

Instead of asking your customers to fill in a form, you can create a conversation to gather information about the customer. For example, you can set up a custom entity that asks for the customer's name and then include their name in articles. Here's how to do that:

In the AI Console, go to Knowledge > Entities.
Choose (Create Entity) in the top right to create a new entity.
Select custom entity for entity type.
Provide a name and optionally a description for your entity.
The entity name can contain letters, numbers and underscores. Spaces are not allowed.

You can use the description to give your entity a more meaningful name or description that helps you identify it later.

Example: Name your entity UserDetails.
Set the life cycle of the entity to Persistent.
This way, the bot does not forget the user?s first name once they enter one.

You can also a set a life cycle for the individual properties keeping in mind their life cycle can't be longer than the life cycle of the entire entity. See this article to learn more about how the different life cycle options work.

Fill out the entities table.

Example:

Table 1. Property asking for customer's name
Name	Detect	Bot Query	ErrorMessage	Life Cycle
FirstName	Text	Hi, I'm your virtual assistant. What's your first name?	N/A	Persistent

Note: Since it's not possible to validate text-type custom entity properties, you can't enable error messages for such properties.

To learn more about the property options for custom entities, see this article.

Save your changes.
Now go to Knowledge > Articles.
Create a new article or open an existing one and add the entity in the article's body.
Example: Intent: I want to go to Greece for a vacation

Body: ?Here are our current offers for you, [[UserDetails.FirstName]]:?

<add options to the article>
Publish the article.

When an article that uses the UserDetails entity is returned as a response, first the entity question is presented then the article is presented with the name they provided. If the conversation continues and the another article with this entity is returned as a response, the bot won't ask the question again, because the customer name is retained for the duration of the session, as defined by the persistent life cycle option.

Announcements

Bold360 21.10 Release Notes

Bold360 21.10 release notes

Bold360 version 21.10 contains the following new enhancements:

Enforcing HTTPS and removing HTTP across widget scripts

Going forward, there will no longer be an option to choose (non-secure) HTTP-only connections when generating widget touchpoint scripts. HTTPS will be enforced across all touchpoints going forward and HTTP-only widget configurations will no longer be supported as of December 31, 2021. Any widget script using HTTP only will need to be changed by this date in order to continue uninterrupted

Access to the Genesys DX AI management (*.nanorep.co) will only be accessible through HTTPs

In-product announcements will be present to raise awareness of this change

Important: Any widget script using HTTP only will need to be changed by this date in order to continue uninterrupted.

In-Product Rebranding

As part of the transformation to Genesys DX, the product interfaces are now rebranded to reflect this change. Logos, product names, and company links are now updated to Genesys branding and is present within each of the product interfaces.

getEstimatedWaitTime API call

Using the "getEstimatedWaitTime" API call will provide the estimated wait time that the visitor would spend waiting before starting a live chat with an agent.

Details on using this API can be located in this article.

Bold360 21.11 Release Notes

Bold360 version 21.11 contains the following new enhancements:

New KB Launchpad Intent Library for COVID-19/Vaccinations

In order to help businesses with providing just-in-time information related to updates to COVID-19 and vaccination protocols, a new entry in the KB Launchpad is now available with intents that can be used to deploy knowledge to keep your workforce informed of new policies and information that you may need to enforce.

Not familiar with the KB Launchpad? The KB Launchpad contains pre-defined intent libraries to help you add industry and use-case specific questions/intents to your KBs with your own specific responses to help with adding commonly asked questions for newly created KBs.

We will be enabling the KB Launchpad as a default setup option on all accounts shortly but contact your Account or Success Manager to get it enabled early if necessary.

ICO Cookie Compliance

In order to support ICO cookie compliance in regions that require end-user consent for allowing cookies to be set, Genesys DX now complies with this standard by making the tracking and analytics related cookies that are set through the touchpoint and visitor monitoring HTML snippets to be optional.

By default, all cookies will continue to be set upon page load. To restrict these cookies from loading automatically and only upon end-user consent, additional steps will be required on the website that the Genesys DX code is being deployed to.

You can learn more about what this compliance is and how to update your Genesys DX deployment to be compliant by reviewing the details in this article: ICO Cookie Compliance.