Information Tasks



Information tasks are used by chatbots to look up data or pull reports for users and return easy-to-consume results or a link to the results for extended data. Users can identify the specific parameters or filters for the information delivered – such as the quantity of results – for bots to deliver information in a way that’s simple for recipients to scan, process, and reuse.

For example, let’s say you have a Shopping Bot that provides search results to an end-user plus a link to view those results in detail with a means to add those items to a shopping cart list. You can define an information task to display the results of the search with a link to view the search results in detail, and then when the link is clicked, display a web page that shows items that end-user can add to the shopping cart.

In the following illustration, the Relay Bot has several tasks defined, one of which is an information task used to display the View Items link in the search results.

When the user clicks View Items, an information report is displayed in a new tab with detailed product information and selectable results that can be added to a shopping cart as shown in the following illustration.

In Bot Builder, you can define the following report types for the bot response:

• Table Report – The report is displayed in a table format with variable-width columns.
• Fixed-Column Table Report – The report is displayed in a table format with fixed-width columns.
• Card Layout Report – The report is displayed as a list of cards, or text boxes with variable formatted data, including images.
• Card Layout with Actions  Report – The report is displayed as a list of cards, or text boxes with variable formatted data, including images, plus an option to associate action tasks to the report, such as Add to Cart.
• Card Layout with Group By Report – The report is displayed as a list of cards, or text boxes with variable formatted data that can be group by a parameter key, such as date, size, or location. The card report includes images, plus an option to associate action tasks to the report, such as Add to Cart.
• Shopping Cart Layout with Actions – The report is displayed as a list of shopping cart options, or text boxes with variable formatted data, including images, plus an option to associate action tasks to the report, such as Add to Cart.
• Weather Info Report – The report is specifically designed to show a serial data string of weather info by date, the day of the week, or forecast period.

Other Examples:

• Provide account summaries
• Show loyalty reward points
• Look up a person’s information
• Get a summary view of outstanding items
• Pull a list of inventory
• Fetch team status information
• Update critical information

Process

The steps that you need to complete to define an information task consists of four basic steps.

Step 1:  General Settings

The first step is to define how the task is displayed to the end-user such as the task name, connection mode, descriptions, and other advanced settings for NLP ignore words, search keywords, error messages, task confirmation messages, mapping restrictions, and Kore.ai Bot Store settings.

Follow these steps to configure the general settings for an Information task:

1. Open the bot in which you want to create the Information Task.
2. Hover over the side navigation panel of the bot, and click Bot Tasks.
3. On the Bot Tasks page, hover over the Information Task tab and click the plus icon.
4. Enter a name for the task, which also doubles up as the display name. Bot Store uses the display name of the task. You can change the display name if needed. The Create Information Task dialog opens.
5. Enter the following required details for the task, and then click Create & Proceed:
   

   Field Name	Description
   Task Name	The name of the task as displayed everywhere in the application and end-user channels.
   Display Name	The name of the task as it gets displayed in the Kore.ai Bot Marketplace. It is the same as the task name unless you want to change it.
   Connection Type	The connection type for Information Tasks is always web service. The web service sends data to Kore.ai when it polls using the end user credentials. This setting is read-only for information tasks.
   Connection Mode	This is the communications protocol connection type for your task as a web service. The web service sends data to Kore.ai when polled by Kore.ai using the end-user account login credentials. REST – The task uses a REST API connection that is protocol-independent to exchange messages and to handle CRUD operations for web services. SOAP – The task uses a SOAP API connection based on XML protocols for message exchange.
   Long Description	The long description of the information task.

Advanced Settings

To configure the advanced settings for the task, expand the section and enter the relevant details.

Field Name	Description
Turn Off Confirmation Messages	Select Yes to disable confirmation of the execution of a task when using NLP.
Mapped Only Action Task	Select to only display this action task to an end-user if mapped from another task in a flow. When Yes is selected, the information task is not visible in an end-user search for information tasks.
Search Keywords	Specify one or more search words an end-user can use to help locate this task in the Kore.ai Bot Store.
Task Demo Link	Enter a www.youtube.com link to display a demo icon next to the task name in the Bot Store. The following illustration shows a bot task defined with a Task Demo Link.
Authorization is required for Accessing the WSDL File (Applies only to SOAP requests)	Select Yes to use authentication if web service authorization is required to access the WSDL for SOAP requests. When Yes is selected, the Authentication defined for the API request is used to access the WSDL. This setting is only available when the task Connection Mode is set to SOAP.
Get Optional Fields	Select Yes to require the end-user to select and then enter at least one of the available optional parameters.
Ignore Words	Enter one or more words to ignore for the task name, and then press enter after each word. The list of words to ignore is processed by the Bots Platform before interpreting the user input. This means the Bot can respond faster to user input and provide the correct task by filtering out words that apply to many tasks but do not help to identify which task. For example, a user may input, I want to get the weather forecast for today. To return the correct action task to the user, the Bots Platform interpreter only needs to recognize three words, weather, forecast, and today. The rest of the words can be ignored. The Kore.ai Bots interpreter is already defined with a set of generic ignore words, so words like I, you, want, get, etc., do not need to be defined as ignore words. If your Bot uses the same words for many or all tasks, for example, your company name, you might add your company name as an ignore word.
Error Messages	Edit or add custom HTTP Status Codes and error messages for your Bot. For more information, see Customizing Error Messages.

Step 2: Authentication Settings

If required for your task, you will define the authentication, for example, basic authorization, OAuth, or API Key.

Depending on the Bot action task, you may need to define how a user must be authenticated to initiate the action task. For example, Twitter can have an action task using web services that require an end-user to authenticate, usually with a login username and password, to allow Kore.ai to access the end-user account for data before executing the action task.
You can define an Authorization profile or use an existing one. All authorization profiles, whether you create them at a task level or a bot level, can be used across all bot tasks.

1. To get started with defining the Authorization for a task, from the API Request tab, click the Expand  icon in the Authorization section.
2. If you have previously defined authentication for this task, you can select it in the Authorization Provider drop-down list.
3. If your task does not require authentication, you can select None as the Authorization provider.
4. To define a new authorization provider, click Create New to display the New Authorization Mechanism dialog.
5. In the dialog, from the Authorization Type drop-down list, select the type of authorization used by your Bot. You can choose one of the following types of authorization:
   • Basic Auth – A standard protocol to collect username and password information. Kore.ai uses SSL encryption in combination with basic authentication to help secure end-user information. Click on the below link for the configuration details.
     Setting Up Authorization using Basic Auth
     The following illustration is an example of the Basic Auth fields that you must define to enable basic authorization for your task.To define basic authorization, select Basic Auth in the Authorization Type field. Then specify a Name for the authorization to be displayed in the Bot builder user interface.

     Defining Tenancy

     If required, in the Subdomain section, select Yes if the base URL for a web application or user interface the uses a tenant name in the URL. For example, kore is the tenant organization for a web service using tenants as www.kore.someCompany.com.
     In the following example configuration, the tenancy URL contains the {tenant} organization placeholder.
     

     Adding Form Fields

     If the default username and password fields do not meet your needs, you can add new fields displayed to the end-user by adding authorization form fields. To add fields on the authorization form, click + Add Form Field. The following illustration is an example of a definition to add a password field to the authorization dialog.
     
     The following table describes the fields used to define an authorization IDP form field.

     FIELD NAME	DESCRIPTION
     Field Title	Specify the name of the field displayed to the end-user in the authentication dialog.
     Field Key	The value represents the end-user input value to the authenticating service.
     Help Hint	The help text displayed in the field to describe what should be entered into the field.
     Field Type	When Advanced Options is selected, specify the type of field displayed in the end-user interface to collect the user input assigned as the value for the Field Key, one of: Textbox Password
     Mandatory	When Advanced Options is selected, select if the end-user must define this field to complete authentication.
     Data Type	When Advanced Options is selected, specify the type of data expected as input from the end-user, for example, String.
     Visibility	When Advanced Options is selected, specify if the authentication field should be visible, hidden, or displayed as read-only.

     Adding Authorization Fields

     By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click + Add Authorization Field and then define the fields as shown in the following illustration.
     
     In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

     • Header – The Bot expects the authorization fields as part of the header of the request.
     • Payload – The Bot expects the authorization fields as part of the content of the body of the request.
     • Query String – The Bot expects the authorization fields as a query in the body of the request.
     • Path Param – The Bot expects the authorization fields as part of the URL path for the request.

     In the Field Key field, enter the name of the field for the selected Field Type.
     In the Field Value field, enter the value for the Field Key specified.
     Click Done. The new authorization field is added in the Authorization Fields section.
     To add additional authorization fields, click Add in the Authorization Fields section.
     In the Authorization Check URL field, optionally define a URL that can be used to test the authentication settings from Bot Builder before you deploy the task with the authorization mechanism. You can use dynamic fields, path parameter fields, query fields, and so forth, to define the test URL, for example,
     https://kore.someCompany.com/sap/opu/odata/sap/{{authfield1}}/?$format=json
     In the Access Using a Connector section, select Yes to enable access for Kore.ai Bots using the Kore.ai Connector agent. If your domain does not have any active Kore.ai Connectors defined, a warning message is displayed to contact the Bots Admin Console system administrator. For more information, see Using the Kore.ai Connector in the Bots Admin Console documentation.
     Click Save to save the authorization settings and close the New Authorization Mechanism dialog.

     Testing the Authorization – Basic Auth

     After you save the authentication, if you defined an Authorization Check URL for your new authorization type, you can test your authorization definition on the Authorization tab when you click Test Authorization before continuing to develop the remaining steps of your task.
     
     When you click Test Authorization, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section, as shown in the following illustration.
     
     To configure the Test Authorization – Basic Auth

     1. In the Auth Check URL field, verify or enter the URL to test the authentication configuration.
     2. If your bot uses subdomains, the Tenancy field is displayed and you must specify the tenant.
     3. Enter your User Name and Password for the web service.
     4. Select the content type expected for the URL in the Content-Type field.
     5. For testing the URL, the Method field is read-only and set to GET.
     6. Click Test to begin the authorization test.

     When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failure, is displayed to the immediate right of the Test Authorization button as shown in the following illustration.
     
     If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs as shown in the following illustration.
     

     How it all Works – Basic Auth

     When basic authorization is used for a task, the Kore.ai application automatically prompts the user for log in credentials to access the web application or web service as shown in the following illustration.
     
     After the end-user is authorized, the settings are saved using the following naming syntax:

     {{ First Name }} {{ Last Name }} {{ Bot Name }} {{ Account # }} {{ Sequence # }}

     For example, John Smith’s Twitter Account #1.
     The Kore.ai application can access the web application or web service for all future task requests using this account. In addition, the end-user can reuse the account for other tasks for the same Bot.
     

   • OAuth v2 password grant type – Define a custom authorization type for non-standard web service authorization types. Click on the link below for the configuration details.
     Setting Up Authorization using oAuth v2 password grant
     
     The following illustration is an example of the oAuth v2 password grant authorization type fields that you must define to enable a customized authorization for your task.To define a custom authorization, select oAuth v2 password grant in the Authorization Type field. Then specify a Name for the authorization to be displayed in the Bot builder user interface.

     Defining Tenancy

     If required, in the Subdomain section, select Yes if the base URL for a web application or user interface the uses a tenant name in the URL. For example, kore is the tenant organization for a web service using tenants as www.kore.someCompany.com.
     In the following example configuration, the tenancy URL contains the {tenant} organization placeholder.
     

     Adding Form Fields

     If the default username and password fields do not meet your needs, you can add new fields displayed to the end-user by adding authorization form fields. To add fields on the authorization form, click + Add Form Field. The following illustration is an example of a definition to add a password field to the authorization dialog.
     
     The following table describes the fields used to define an authorization IDP form field.

     FIELD NAME	DESCRIPTION
     Field Title	Specify the name of the field displayed to the end-user in the authentication dialog.
     Field Key	The value represents the end-user input value to the authenticating service.
     Help Hint	The help text displayed in the field to describe what should be entered into the field.
     Field Type	When Advanced Options is selected, specify the type of field displayed in the end-user interface to collect the user input assigned as the value for the Field Key, one of: Textbox Password
     Mandatory	When Advanced Options is selected, select if the end-user must define this field to complete authentication.
     Data Type	When Advanced Options is selected, specify the type of data expected as input from the end-user, for example, String.
     Visibility	When Advanced Options is selected, specify if the authentication field should be visible, hidden, or displayed as read-only.

     Adding Authorization Fields

     By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click + Add Authorization Field and then define the fields as shown in the following illustration.
     
     In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

     • Header – The Bot expects the authorization fields as part of the header of the request.
     • Payload – The Bot expects the authorization fields as part of the content of the body of the request.
     • Query String – The Bot expects the authorization fields as a query in the body of the request.
     • Path Param – The Bot expects the authorization fields as part of the URL path for the request.

     In the Field Key field, enter the name of the field for the selected Field Type.
     In the Field Value field, enter the value for the Field Key specified.
     Click Done. The new authorization field is added in the Authorization Fields section.
     To add additional authorization fields, click Add in the Authorization Fields section.

     Defining the Token URL

     In the Token URL field, optionally define a URL that can be used to test the authentication settings from Bot Builder before you deploy the task with the authorization mechanism. You can use dynamic fields, path parameter fields, query fields, and so forth, to define the test URL, for example,
     http://{tenant}.someCompany.com/test/{{tokenId}}
     In the Token URL Method field, select the HTTP request method type for the Token URL. One of PUT, POST, PATCH, DELETE, and GET.
     In the Token URL Content Type field, select the content type expected from the Token URL. One of: JSON, RSS, XML, URL Encoded JSON, CSV, Text, Twitter Encoded JSON, Multipart/Form-data,Multipart/Related, or Oracle ADF.
     In the Access Using a Connector section, select Yes to enable access for Kore.ai Bots using the Kore.ai Connector agent. If your domain does not have any active Kore.ai Connectors defined, a warning message is displayed to contact the Bots Admin Console system administrator. For more information, see Using the Kore.ai Connector in the Bots Admin Console documentation.
     Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

     Testing the Authorization

     After you save the authentication, if you defined an Authorization URL for your new authorization type, you can test your authorization definition on the Authorization page when you click Test Authorization before continuing to develop the remain steps of your task.
     
     When you click Test Authorization, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section, as shown in the following illustration.
     
     Click Test to begin the authorization test. When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failure, is displayed to the immediate right of the Test Authorization button. If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs as shown in the following illustration.
     
     

   • OAuth v2 client credential –
   • OAuth v1 – Enables web applications or web services to access protected resources using an API without end-users having to disclose their log on credentials to Kore.ai. Click on the link below for the configuration details.
     Setting Up Authorization using OAuth v1
     
     OAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.To use OAuth, you must first register an account with the web application as you will need the log in credentials for that application to configure the settings for the authorization mechanism.

     How OAuth v1 Works

     1. The Kore.ai application obtains an unauthorized request token from the web application. The Kore.ai application redirects the user to a login dialog at the web application.
     2. The user authorizes the request token, associating it with their account. The web application redirects the user back to the Kore.ai application.
     3. The Kore.ai application exchanges the request token for an access token.
     4. The access token allows the Kore.ai application to access a protected resource at the provider, on behalf of the user.

     The following illustration is an example of the oAuth v1 authorization type fields that you must define to enable a customized authorization for your task.
     
     To define oAuth v1, define the fields described in the following table.

     FIELD NAME	DESCRIPTION
     Authorization Type	Set to oAuth v1.
     Callback URL	The URL used by the web application or web service to redirect the end-user after end-user authorization is complete. This value, https://idp.kore.ai/workflows/callback/,  is provided as a read-only value by the Kore.ai application when you define oAuth v1 settings.
     Identity Provider Name	The name of the web application or web service, for example, Twitter. This field is required.
     Consumer Key	The value provided as the Kore.ai application identification to the web application. This field is required.
     Consumer Secret	The secret value provided by the Kore.ai application to establish ownership of the Consumer Key. This field is required.
     Request Token Link	The URL used by the Kore.ai application to obtain an unauthorized request token. A request token is the value used by the Kore.ai application to obtain authorization from the end-user to obtain an access token. For example, https://{tenant}.someCompany.com/oauth/request_token. After end-user authorization, an access token can be requested by the Kore.ai application. This field is required.
     Access Token Link	The URL used to exchange the end-user authorized request token for an access token. The access token is the value used by the Kore.ai application to gain access to the web application or web service on behalf of the end-user, instead of using the end-users log on credentials. For example, https://{tenant}.someCompany.com/oauth/access_token. This field is required.
     User Authorization Link	The URL used to obtain end-user authorization for the Kore.ai application to access the web application or web service using the access token. For example, https://{tenant}.someCompany.com/oauth/authorize. This field is required.
     Access Using a Connector	Select Yes to enable access for Kore.ai Bots using the Kore.ai Connector agent. This option is only visible if a Kore.ai Connector agent is configured and enabled in your enterprise on-premises network. For more information, see Using the Kore.ai Connector.

     Defining Tenancy

     If required, in the Subdomain section, select Yes if the base URL for a web application or user interface the uses a tenant name in the URL. For example, kore is the tenant organization for a web service using tenants as www.kore.someCompany.com.
     In the following example configuration, the tenancy URL contains the {tenant} organization placeholder.
     

     Adding Additional Fields

     Click + Add Additional Fields to open the Additional Fields dialog, and then enter one or more key/value pairs that represent additional authorization input fields if required as shown in the following illustration.
     
     Specify the following fields:

     • Field Key – The name of the custom field to specify for authorization.
     • Field Value – The value of the custom field to specify for the authorization.

     Click Add to save the Additional Field.
     To add more Additional Fields, click Add in the Additional Fields section.

     Adding Authorization Fields

     By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click + Add Authorization Field and then define the fields as shown in the following illustration.
     
     In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

     • Header – The Bot expects the authorization fields as part of the header of the request.
     • Payload – The Bot expects the authorization fields as part of the content of the body of the request.
     • Query String – The Bot expects the authorization fields as a query in the body of the request.
     • Path Param – The Bot expects the authorization fields as part of the URL path for the request.

     In the Field Key field, enter the name of the field for the selected Field Type.
     In the Field Value field, enter the value for the Field Key specified.
     Click Add. The new authorization field is added in the Authorization Fields section.
     To add additional authorization fields, click Add in the Authorization Fields section.

     Testing the Authorization

     After you save the authorization, you can test your authorization definition on the Authorization page when you click Test Authorization before continuing to develop the remain steps of your task.
     
     When you click Test Authorization, the test is executed using the authentication token URLs and the Consumer Key and Consumer Token. If the tenancy was defined, the Test Authorization dialog is displayed as shown in the following illustration.
     
     Click Test to begin the authorization test. When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failure, is displayed to the immediate right of the Test Authorization button. If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs as shown in the following illustration.
     
     

   • OAuth v2 – The newest version of OAuth protocol focusing on specific authorization flows for web applications and web services. Click on the link below for the configuration details.
     Setting Up Authorization using OAuth v2
     
     OAuth v2 is the new version of the open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.To use oAuth v2, you must first register an account with the web application as you will need the log in credentials for that application to configure the settings for the Authorization Mechanism.

     How oAuth v2 Works

     1. The Kore.ai application redirects the user to a login dialog at the web application.
     2. The user authenticates.
     3. The web application redirects the user back to the Kore.ai application with an access token.
     4. The Kore.ai application validates the access token.
     5. The access token allows the Kore.ai application to access a protected resource at the provider, on behalf of the user.

     The following illustration shows the fields to define for the oAuth v2 Authorization Type.
     
     To configure oAuth v2, define the fields described in the following table.

     FIELD NAME	DESCRIPTION
     Authorization Type	Set to oAuth v2.
     Callback URL	The URL used by the web application or web service to redirect the end-user after end-user authorization is complete. This value, https://idp.kore.ai/workflows/callback/ is provided as a read-only value by the Kore.ai application when you define oAuth v2 settings.
     Identity Provider Name	The name of the web application or web service, for example, Asana. This field is required.
     Client ID	The ID of the Kore.ai client.
     Client Secret Key	The value provided as the Kore.ai application authentication based on the Client ID to the web application.
     Authorization URL	The URL used to obtain end-user authorization for the Kore.ai application to access the web application or web service using the access token. This field is required.
     Access Using a Connector	Select Yes to enable access for Kore.ai Bots using the Kore.ai Connector agent. This option is only visible if a Kore.ai Connector agent is configured and enabled in your enterprise on-premises network. For more information, see Using the Kore.ai Connector.
     Authorization URL	The URL used by the Kore.ai application to obtain an unauthorized request token. A request token is a value used by the Kore.ai application to obtain authorization from the end-user to obtain an access token. After end-user authorization, an access token can be requested by the Kore.ai application. This field is required.

     Defining Tenancy

     If required, in the Subdomain section, select Yes if the base URL for a web application or user interface the uses a tenant name in the URL. For example, kore is the tenant organization for a web service using tenants as www.kore.someCompany.com.
     In the following example configuration, the tenancy URL contains the {tenant} organization placeholder.
     

     Adding Additional Fields

     Click + Add Additional Fields to open the Additional Fields dialog, and then enter one or more key/value pairs that represent additional authorization input fields if required as shown in the following illustration.
     
     Specify the following fields:

     • Field Key – The name of the custom field to specify for authorization.
     • Value – The value of the custom field to specify for the authorization.

     Click Add to save the Additional Field.
     To add more Additional Fields, click Add in the Additional Fields section.

     Adding Authorization Fields

     By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click + Add Authorization Field and then define the fields as shown in the following illustration.
     
     In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

     • Header – The Bot expects the authorization fields as part of the header of the request.
     • Payload – The Bot expects the authorization fields as part of the content of the body of the request.
     • Query String – The Bot expects the authorization fields as a query in the body of the request.
     • Path Param – The Bot expects the authorization fields as part of the URL path for the request.

     In the Field Key field, enter the name of the field for the selected Field Type.
     In the Field Value field, enter the value for the Field Key specified.
     Click Add. The new authorization field is added in the Authorization Fields section.
     To add additional authorization fields, click Add in the Authorization Fields section.

     Testing the Authorization

     After you save the authorization, you can test your authorization definition on the Authorization page when you click Test Authorization before continuing to develop the remain steps of your task.
     
     When you click Test Authorization, the test is executed using the authentication token URLs and the Client ID and Client Secret Key. If the tenancy was defined, the Test Authorization dialog is displayed as shown in the following illustration.
     
     Click Test to begin the authorization test. When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failure, is displayed to the immediate right of the Test Authorization button. If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs as shown in the following illustration.
     

   • API Key – An identification and authorization token generated or provided by a web application or web service used to identify the incoming application request, and in some cases, also provide authentication for secure access. Click on the link below for the configuration details.
     Setting Up Authorization using an API Key
     
     An API key can act as both a unique identifier and a secret token for identification as well as authentication to provide a set of access rights on the associated API. Instead of prompting the end-user for both a username and password for access, the user is prompted only for an API key when configuring the task.To use the API Key Authorization Type, you must first register an account with the web application and then generate an API Key for that application to configure the settings for the Kore.ai authorization mechanism.The following illustration shows the fields to define for the API Key Authorization Type.To define an API key authorization, select API Key in the Authorization Type field. Then specify a Name for the authorization to be displayed in the Bot builder user interface.

     Defining Tenancy

     If required, in the Subdomain section, select Yes if the base URL for a web application or user interface the uses a tenant name in the URL. For example, kore is the tenant organization for a web service using tenants as www.kore.someCompany.com.
     In the following example configuration, the tenancy URL contains the {tenant} organization placeholder.
     

     Adding Form Fields to the Authorization Form

     If the default username and password fields do not meet your needs, you can add new fields displayed to the end-user by adding authorization form fields. To add fields on the authorization form, click + Add Form Field. The following illustration is an example of a definition to add a password field to the authorization dialog.
     
     The following table describes the fields used to define an authorization IDP form field.

     FIELD NAME	DESCRIPTION
     Title of Field	Specify the name of the field displayed to the end-user in the authentication dialog.
     Field Key	The value represents the end-user input value to the authenticating service.
     Help Hint	The help text displayed in the field to describe what should be entered into the field.
     Field Type	When Advanced Options is selected, specify the type of field displayed in the end-user interface to collect the user input assigned as the value for the Field Key, one of: Textbox Password
     Mandatory	When Advanced Options is selected, select if the end-user must define this field to complete authentication.
     Data Type	When Advanced Options is selected, specify the type of data expected as input from the end-user, for example, String.
     Visibility	When Advanced Options is selected, specify if the authentication field should be visible, hidden, or displayed as read-only.

     Adding Authorization Fields

     By default, authorization fields are configured as part of the header of the task request message. If your task request requires additional authorization fields or the expected authorization is not part of the header, for example, social security number or PIN, click + Add Authorization Field and then define the fields as shown in the following illustration.
     
     In the Field Type field, you can select one of the following depending on where in the task request message and the type of authorization fields that are required.

     • Header – The Bot expects the authorization fields as part of the header of the request.
     • Payload – The Bot expects the authorization fields as part of the content of the body of the request.
     • Query String – The Bot expects the authorization fields as a query in the body of the request.
     • Path Param – The Bot expects the authorization fields as part of the URL path for the request.

     In the Field Key field, enter the name of the field for the selected Field Type.
     In the Field Value field, enter the value for the Field Key specified.
     Click Add. The new authorization field is added in the Authorization Fields section.
     To add additional authorization fields, click Add in the Authorization Fields section.

     Testing the Authorization – API Key

     After you save the authentication, if you defined an Authorization Check URL for your new authorization type, you can test your authorization definition on the Authentication tab when you click Test Authorization before continuing to develop the remain steps of your task.
     
     When you click Test Authorization, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section, as shown in the following illustration.
     
     To configure the Test Authorization – API Key

     1. In the Auth Check URL field, verify or enter the URL to test the authentication configuration.
     2. If your bot uses subdomains, the Tenancy field is displayed and you must specify the tenant.
     3. Enter the API key for the application in the API Key field.
     4. Select the content type expected for the URL in the Content-Type field.
     5. For testing the URL, the Method field is read-only and set to GET.
     6. Click Test to begin the authorization test.

     When the validation of authentication is complete, the Test Authorization dialog is closed and the results of the validation, either success or failure, is displayed to the immediate right of the Test Authorization button. If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs as shown in the following illustration.
     
     

Step 3:  API Request

If required for your task, you can define a request object to, for example, provide a dynamic drop-down choice for the end-user to select from to complete the task. On the information task API Request tab, you can define API Parameters, optional API task Initializer, API Request pre- or post-processor, and the API Request. You will also need to add a Response Sample expected from your API Request payload.

You can also configure an information task request using SOAP in which case you need to configure the WSDL URL, and Connectors.

Step 4:  Defining the Bot Response

The Bot response provides a message to the end-user to inform the end-user of the status or completion of the task. On the Bot Response tab for a task, you can define the message to display to the end-user from the API request payload. You can define a default response for all channels, and optionally define channel-specific messages.

After you describe your Bot alert task General tab settings and then configure the alert task API request chain, you are ready to define how the alert task results are displayed to the end-user. This section describes how to configure an alert task response.
To define the response object for an alert task, there are two sections:

• Report Template Definition – For some tasks, you may want to display report data to the end-user as a link that can display the payload response using a template, such as a table, contact card, or formatted for a specific message type such as a weather report.

  Note: This section is not used for webhook alert tasks, action tasks, or RSS alert tasks.

  Configuring the Report Template Definition

  
  To add a link to a task to provide more information or a report, you can define a link and information to display for the report as a table, weather report, or contact card in the end-user application.
  To get started with defining the Report Template Definition for a task, on the Bot Response tab, click the Expand icon in the (Optional) Report Template Definition section as shown in the following illustration.
  
  To enable a report link for the task, select Yes to display the Report Template Definition section shown in the previous illustration.
  When you add a link to a task response message, the end-user for the Bot has the ability to select the link and get more details, such as a table of values for Closed Sales Opportunities in the SalesForce Bot.
  Define the following parameters to create a link in a task response message for the end-user to request a report for additional information from the initial task response message:

  • Link Title – The link text displayed to the end-user in the task post, for example, View Shopping Cart.
  • Header – The title displayed when the report is displayed to the end-user, for example, These are the items in your Shopping Cart.
  • Details – End-user help information displayed directly below the Header in the report that describes the content of the report, for example, Review your Shopping Cart, and then click Continue when you are ready to place your order.
  • Template – Select one of the following format templates to display the data from the task response. For each type, define the Column Name, Key Mapping, Data Type, and template-specific options.
    • Table – Data is presented in a table format with defined columns. Each mapping for the Table template can be set to Is Sortable, Display as an image, and Display it as a link. For more information, see Defining a Table Report.
    • Fixed Column Table – Data is presented in a table format with the one or more columns fixed. Each mapping for the Fixed Column Table template can be set to Is Sortable, Column in fixed, Display as an image and Display it as a link. For more information, see Defining a Fixed-Column Table Report.
    • Card Layout – Data is presented in a contact card format. Each mapping for the Card Layout template can be set to Is Sortable, Display as an image, and Display it as a link. For more information, see Defining a Card Layout Report.
    • Weather Info – Date for a weather service response payload can be defined. Each mapping for the Weather Info template can be set to Is Sortable, Display as an image, and Display it as a link. For more information, see Defining a Weather Info Report.
    • Card Layout with Actions – Displays a list of items with a mapped task link for each item. For more information, see Define a Card Layout with Actions Report.
    • Card Layout with Group By – Displays a list of items grouped by a specific field. For more information, see Define a Card Layout with Group By Report.
    • Shopping Cart Layout with Actions – Displays a list of items with a mapped task link for each item. For more information, see Define a Shopping Cart Layout with Actions Report.

• Message Definition – In this section, you define the look and feel of the data presented to the end-user when the alert is displayed based on the payload delivered by the webhook.
  Defining the Message Definition
  
  You can define two kinds of bot responses for a task:

  • The default for all channels: Author the default title and message response for all channels based on the payload response from the API request and any processors defined. You can create a mixture of data from the response object along with your own inputs, a set of Variable Keys derived from the Kore.ai system, custom variables, and the response sample. The message is displayed as a message, usually as a well-formed HTML message that contains one or more variables, such as the ID number or subject, from the request object data.
  • Channel-specific response: You can also customize a Bot response message for specific channels, for example, Facebook Messenger, Skype, SMS, or Web/Mobile SDK, along with applying predefined message templates (tables, lists, graphs, etc.) for selected channels.

  Message Definition Editor Features

  To open the editor for your Action task, go to Bot Response > Message Definition. The Message Definition editor uses three tabs to offer the following features:

  • Standard Text: Use basic editor controls and HTML markup, and variable keys to define and format the response. Enter text, and then format it using buttons for bold, italics, header styles, hyperlinks, ordered and unordered lists, and inserting lines.
    
  • JavaScript: Add custom code to handle the end-user task response message, declare variables, use variable keys, and interact with third-party applications.
  • Preview: View a sample of the rendered output message, with markup, as the bot users see it.

  Adding Variable Keys

  Follow these steps to add variable keys:

  1. Whether you are using Standard Text or JavaScript mode, to add a variable key, place the cursor where you want to add the variable and then click Variable Keys.
  2. In the Request/Response Keys dialog, expand the type of key node that contains the variable you want to insert.
     
  3. Select the variable that you want to add, for example, response.data.idand then click Ok,

  

  Standard Keys

  Standard Keys are the following Kore.ai variable placeholders for reusable data.
  

  • _labels _: Returns the friendly label in place of a GUID. For example, when user data is requested from a web service API, the ID of a project or workspace returned is a GUID. You can use the _labels_ key to show the user-friendly name of the GUID to the end-user instead of the GUID. In Kore.ai, a drop-down control stores the response for the _labels_ key as, for example:

    {
        "_labels_": {
            "15379386734832": "roadlabs.com",
            "26377329985341": "Test Project",
            "workspace": "roadlabs.com",
            "project": "Test Project"
        },
        "_fields_": {
            "workspace": "15379386734832",
            "project": "26377329985341"
        }
    }

    To use the _labels_ key in a response:

    print('<a href="https://app.asana.com/0/' + workspace.id + '+_labels_[workspace.id]);

  • _tenant_ – Returns the tenant for the enterprise when defined. For example, JIRA requires a tenant for URLs, such as koreteam, in https://koreteam.atlassian.net/browse/BBF-3265. You can use the _tenant_ key to build a link in a task response such as:

    var title = request.fields.issuetype.name + ' <a href ="https://' + _tenant_ + '/browse/' + response.key + '" target = "_blank">' + request.fields.summary + '</a>  has been created.';

  • _fields_ – Used to return a task field input provided by the end-user that is not part of a payload response. For example, in a JIRA task, the end-user is prompted to enter a workspace name. You can use the _fields_ key to store the end-user input as:

    _fields_["workspace"]

  • _last_run – Used to return the UTC date timestamp of a web service poll using ISO 8601 format, for example, 2016-03-05T12:44:38+00:00. For example, if a web service request returns all activity in a payload response, you can use the _last_run key to filter results displayed before or after the value for_last_run

  Session Keys

  Session Keys are Kore.ai variable placeholders for user data specific to a single session instance.
  

  • UserContext.get(“_id”) – The Kore.ai userId.
  • UserContext.get(“emailId”) – The email address associated with the userId.
  • UserContext.get(“lastName”) – The last name of the user.
  • UserContext.get(“firstName”) – The first name of the user.
  • UserContext.get(“profImage”) – The image or avatar filename of the user.
  • UserContext.get(“profColor”) – The account color for the user.
  • UserContext.get(“activationStatus”) – The account status of the user.
  • UserContext.get(“jTitle”) – The title of the user, if defined.
  • UserContext.get(“orgId”) – The organizational ID of the user account, if defined.
  • UserContext.get(“customData”) – A developer defined custom key.
  • UserContext.get(“identities”) – Alternate user IDs, if defined.

  Additional session keys may be available depending on how the Bot task is defined and the context of keys available for that task. For more information about session and context keys, see Using Session and Context Variables in Tasks.

  Response Keys

  Response Keys are parsed directly from your Response Sample text in the API Response tab. Response Keys vary depending on the Response Sample defined.
  The following list is an example of Response Keys available for an Asana task.

  request.data.workspace
  request.data.projects
  request.data.name
  request.data.notes
  labels.498346170860
  labels.30887755353556
  labels["data.workspace"]
  labels["data.projects"]
  _tenant_
  response.data.id
  response.data.created_at
  response.data.modified_at
  response.data.name
  response.data.notes
  response.data.completed
  response.data.assignee_status
  response.data.completed_at
  response.data.due_on
  response.data.due_at
  response.data.workspace.id
  response.data.workspace.name
  response.data.num_hearts
  response.data.parent
  response.data.followers[0].id
  response.data.followers[0].name
  response.data.hearted
  response.data.assignee
  response.data.projects[0].id
  response.data.projects[0].name
  response.data.memberships[0].project.id
  response.data.memberships[0].project.name
  response.data.memberships[0].section

  Report Keys

  Report Keys are Kore.ai variable placeholders that you can use in Report Template Definitions and Bot Responses to show links for additional information in a message that a user can click.
  

  • reportInfo.reportLink – The link defined in the Report Template Definition section for this task.
  • reportInfo.reportTitle – The title defined in the Report Template Definition for this task.

  Previewing the Response

  On the message editor, click Preview to generate a preview of your response using one of the following options:

  • Test & Preview – Opens the task setup page for your Bot to define the task settings, authenticate, and then shows a preview of your response generated through your third-party web service, for example, Asana.
  • Preview with sample response – Generates the preview using the sample data provided with the key-value pairs defined in the Response Sample section on the API Request tab for the task.

  

  Examples of Custom JavaScript Response

  The following examples show response objects using JavaScript to define the Post Title and Post Description sections that display output messages to the end-user when the task response message is sent.
  In the following example, the variable labeled desc is only displayed if the value for the caption is defined in the JSON response.

  var desc = (caption !== "undefined" ? caption : "")

  In the next example, a clickable URL using the task title is displayed in the task response message.

  var tasklink = '' + title + '';

  In this last example, the link variable depends on the type, either video or photo. Based on the type, the proper link is displayed.

  var link = "";
  switch (type) {
      case "video":
          var video = (typeof(video_url) != "undefined") ? video_url : permalink_url;
          link = '<video controls><source src ="' + video + '" type="video/mp4"></video>';
          break;
      case "photo":
          link = '<img src="' + image_permalink + '"></img>';
          break;
  }

  You can create custom JavaScript to handle task-specific requirements on the JavaScript tab based on the payload response for the task.

  Channel-Specific Bot Response

  A task response message may be dependent on the channel that the response message is displayed in, for example, in the Kore.ai Messenger client, an email, or in a text message. By default, the response message that you configure for Default for all Channels is sent to all channels. However, you can define a specific response for one or more or the 20+ supported channels to display to the end-user in that channel instead of the default response.

  1. To define the response message for a specific channel, click + Add Channel to display the Choose a Channel drop-down list.
  2. Select a channel, for example, Kore.ai, and then configure the response for that channel on the JavaScript tab.

  
  Only one response can be defined for each channel. The following JavaScript examples show how you can override the Kore.ai default formatting template by channel.

  Note: Use the following keys to return default values for:
  response.message – Returns the default message as a string.
  response.message.choices – Returns the options choice or confirmation message types as an array.

  • Slack Channel Override Example

    var message = {};
    var attachments = [];
    var attachment = {
        'text': "Exception occurred during API execution",
        'color': '#FFCC00',
        'attachment_type': 'default'
    };
    attachments.push(attachment);
    message.attachments = attachments;
    print(JSON.stringify(message));

  • FaceBook Channel Override Example

    var message = {
        text: response.message
    };
    var buttons = [];
    for (var i = 0; i < response.choices.length; i++) {
        var choiceItem = response.choices[i];
        if (choiceItem.length > 20) {
            choiceItem = choiceItem.substring(
                0, 18) + '..';
        }
        var element = {
            content_type: 'text',
            title: choiceItem,
            payload: choiceItem
        };
        buttons.push(element);
    }
    message.quick_replies = buttons;
    print(JSON.stringify(message));

  • Email Channel Override Example

    var message = {};
    var text = response.message + ' <br> ';
    for (var i = 0; i < response.choices.length; i++) {
        text = text.concat(
            '<u> + response.choices[i] + ' <
            /u> <br>');
        }
        message.text = text;
        print(JSON.stringify(message));

  • SMS Channel Override Example

    var message = {};
        var indexArray = ['a', 'b', 'c',
            'd', 'e',
            'f', 'g', 'h', 'i', 'j',
            'k', 'l', 'm', 'n', 'o',
            'p', 'q', 'r', 's', 't',
            'u', 'v', 'w', 'x', 'y',
            'z'
        ];
        var text = response.message + '\\n';
        for (var i = 0; i < response.choices
            .length; i++) {
            text = text.concat(indexArray[i] +
                ') ' + response.choices[
                    i] + '\\n');
        }
        message.text = text;
        print(JSON.stringify(message));