AI 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.
  1. 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.

  2. In the AI Console, go to Knowledge > Entities.
  3. Choose (Create Entity).
  4. Select data source entity for entity type.
  5. 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.

  6. 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.
  7. Set the response type to CSV.
  8. Choose LOAD.

    Result: The properties table is now loaded. Properties are the columns that are available in the data source file.

  9. 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.

  10. 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.

  11. Save your changes.
  12. Now go to Knowledge > Articles.
  13. 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: ?

  14. 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 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:

  1. In the AI Console, go to Knowledge > Entities.
  2. Select an existing entity or create a new one.
  3. Choose click URL inputs next to Data Source URL.
  4. 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.

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 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 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?.

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.

  1. 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
  2. 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.
  3. 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.

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).

How can I use entities in user search?

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

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.

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

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 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:

  1. In the AI Console, go to Knowledge > Entities.
  2. Choose (Create Entity) in the top right to create a new entity.
  3. Select custom entity for entity type.
  4. 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.

  5. 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.

  6. 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.

  7. Save your changes.
  8. Now go to Knowledge > Articles.
  9. 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>

  10. 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

Join the DX Community!

Meet fellow DX pros, ask questions, and learn best practices.

Join the DX Community

Featured

Configuring the Genesys DX Product Authentication Service as SSO service

This article provides a step-by-step process for configuring the Genesys DX Product Authentication Service as SSO Service.

  1. Set up your Identity Provider. Read more about setting up your Identity Provider in this article.
     
  2. Login to https://auth.bold360.com/ and click Go to SSO Setup in the bottom left corner.
    Note: If you cannot see the Go to SSO Setup button, contact your support representative or the Genesys CX support.


    You are then navigated to the SSO setup webpage.
    NoteGeneral Settings and Domain are read-only fields, you cannot modify them.
  3. Click Sign-in configuration, and enable the SSO.

     
  4. Choose one of the two configuration methods:

    Method 1: Manual Configuration


    Add your Verification Certificate when you are finished with manual configuration.

    When you add the Verification Certificate, remove the following tags:
    "-----BEGIN CERTIFICATE-----"
    "-----END CERTIFICATE-----"

    A Verification Certificate example with removed BEGIN and END tags: 


    Method 2: SAML IdP metadata URL

    Host your Identity Provider metadata XML file on a publicly accessible URL.


    Note: Since we cache this file for only 2 minutes, please ensure high availability of this file via the specified URL to avoid SSO login failures.
     
  5. Once you have setup your configuration using a method of your choice, save your changes and then click View test login page, where you can test the Single Sign-on login.

    Enter your email /username that uses the domain you have setup in your Identity Provider service and click Continue. You should see this message on a successful login.