Configuring the Action Task Request - REST

After you describe the Bot action task, and then define authentication requirements, you are ready to start configuring the request object that asks for data from your Bot website, system, or web application for the task. This topic describes how to configure the request object for an action task with the Sub Type set to REST.

To define a task web service request object with Sub Type set to SOAP, see Configuring the Action Task Request - SOAP

What Do I Need to Do?

For an action task request in Kore and the Sub Type set to REST, you will need to define:

  • One or more task fields that the end-user must enter information in, for example, a ZIP code, or date, or a choice from a drop-down list, to be used as part of the task request message.
  • One or more request chain objects that define the path to the service that you want to get information from, modify, or delete existing information at that service.
  • Optionally, you can test your request chain object urls.

The following illustration is an example of the Configure the Action Task Request page for a new task with the Sub Type set to REST.

Setting Up an Action Task Field

In the Add Action Task Field section, you can add one or more end-user data input fields to populate task request parameter values, for example, a date, an amount, a drop-down list of user names, etc.

Click Add an Action Task Field to display the Set up Action Task Field dialog. In the Type of Action Task field drop-down list, you can choose one of Payload Field or Query Field which then displays the remaining parameters as shown in the following illustration.

Specify the values for the parameters in the Set up Action Task Field dialog as described in the following table.

Parameter NameDescription
Type of Action Task field The type of action task field used in the Bot task to execute. One of:
  • Query Field - This field type is used as part of a URL path or query within a URL. For example:

    http://app.asana.com/api/workspaces/{queryfield1}/project/{queryfield2}?userId={queryfield3}

  • Payload Field - Use this field type to represent payload data for an HTTP method, such as POST, PUT, GET, DELETE, and so forth. For example:

    {

    "taskId" : "{payloadfield2}"

    "message" : "{payloadfield1}"

    }

Field Name The title of the task input field displayed in the end-user interface, for example, User name to follow, as shown in the following illustration.

Help Hint The help text displayed below the task setting title to describe the task, for example, Enter username/screen name of the user to follow on twitter as shown in the previous illustration.
Field Key The Bot key that represents the end-user input value that you want to collect, for example, screen_name.
Field Key The Bot key that represents the end-user input value that you want to collect, for example, workspace.
Field Type Specifies the type of task input field displayed in the end-user interface to collect user input for the request object to assign to the Field Key value. One of:
  • Date - Displays the Format field where you can select the date format syntax for the end-user to define when the task is configured for their account. In the Select Date Format drop-down list, select one of the following:
    • dd-MM-YYYY - For example, 16-05-1999
    • MM-dd-YYYY - For example, 05-16-1999
    • dd-MM-YY - For example, 16-05-99
    • YYYY-MM-dd - For example, 1999-05-16
  • URL - Displays a text box for the end-user to enter a URL including field validation for a correct URL syntax. In the Placeholder field, enter the help hint displayed in the text box, for example, Enter the URL for the website here.
  • Textbox - Displays a text box for the end-user to enter text as the task input field, typically just a few words. In the Placeholder field, enter the help hint displayed in the text field, for example, Type in the name you want to embroider.
  • Label - Displays a static text label for the end-user when the task is configured in their account, for example, That's all there is to it!
  • Static Dropdown - Displays a drop-down list of choices to the end-user. Click Add Option to begin adding the list of items to display to the end-user with the following parameters:
    • Option Name - The name of the option displayed to the end-user.
    • Option Value - The value the represents the Option Name returned to the application.
    • Searchable - Select to enable dynamic search and display as the end-user enters text in this field, or if no matches, allow free-form entry.
    Click Save. To add additional items, click Add Option again.
  • Dynamic Dropdown - Displays a drop-down list dynamically populated at runtime based on the response from a URL for your Bot, for example, a list of projects for a JIRA task notification. Define the following properties for a dynamically populated dropdown.
    • Endpoint URL - The Bot endpoint URL, for example, https://app.asana.com/api/1.0/workspaces.
    • Endpoint Content Type - The content type expected from the specified endpoint URL. One of: JSON, RSS, XML, URL Encoded JSON, CCV, Text, or Twitter Encoded JSON.
    • Endpoint Method - One of:
      • GET - Specifies an HTTP Request GET method for the task field.
      • POST - Specifies an HTTP Request POST method for the task field.
    • Response Path - The path in the response that contains the desired drop-down list values, for example, data.
    • Label Key - The key for the label of the drop-down option, for example, name.
    • Option Value Key - The key for the value of the drop-down option, for example, id.
    • Searchable - Select to enable dynamic search and display as the end-user enters text in this field, or if no matches, allow free-form entry.
  • Directory - Displays a file directory list dynamically populated at runtime based on the response from a URL for your Bot, for example, a directory of Google Drive files. Define the following properties for a dynamically populated directory list.
    • Endpoint URL - The Bot endpoint URL, for example, https://www.googleapis.com/drive/ve/files.
    • Endpoint Content Type - The content type expected from the specified endpoint URL. One of: JSON, RSS, XML, URL Encoded JSON, CCV, Text, or Twitter Encoded JSON.
    • Endpoint Method - One of:
      • GET - Specifies an HTTP Request GET method for the task field.
      • POST - Specifies an HTTP Request POST method for the task field.
    • Response Path - The path in the response that contains the desired drop-down list values, for example, data.
    • Label Key - The key for the label of the drop-down option, for example, name.
    • Option Value Key - The key for the value of the drop-down option, for example, id.
  • Dynamic Checkbox - Displays a list of dynamically populated selectable checkboxes at runtime based on the response from a URL for your Bot, for example, a list of projects for a JIRA task notification. Define the following properties for a dynamically populated list of checkboxes.
    • Endpoint URL - The Bot endpoint URL, for example, https://app.asana.com/api/1.0/workspaces.
    • Endpoint Content Type - The content type expected from the specified endpoint URL. One of: JSON, RSS, XML, URL Encoded JSON, CCV, Text, or Twitter Encoded JSON.
    • Endpoint Method - One of:
      • GET - Specifies an HTTP Request GET method for the task field.
      • POST - Specifies an HTTP Request POST method for the task field.
    • Response Path - The path in the response that contains the desired list of checkbox values, for example, data.
    • Label Key - The key for the label of the checkbox option, for example, name.
    • Option Value Key - The key for the value of the checkbox option, for example, id.
  • Textarea - Displays a text area box for the end-user to enter text as the task input, typically for several sentences. In the Placeholder field, enter the help hint displayed inside the text area.
  • Checkbox - Displays a list of choices with selectable checkboxes to the end-user. Click Add Option to begin adding the list of items to display to the end-user with the following parameters:
    • Option Name - The name of the option displayed to the end-user.
    • Option Value - The value the represents the Option Name returned to the application.
    • Searchable - Select to enable dynamic search and display as the end-user enters text in this field, or if no matches, allow free-form entry.
    Click Save. To add additional items, click Add Option again.
  • Password - Displays a mandatory password input field for the end-user when the task is configured for their account.
  • Type Ahead - Displays a dynamically populated drop-down list of choices to the end-user at runtime when the user enters three or more characters that match the search results based on the response from the URL defined for the task. For example, a list of projects for a JIRA task notification message. Define the following properties for a dynamically populated drop-down.
    • Endpoint URL - The Bot endpoint URL, for example, https://app.asana.com/api/1.0/workspaces.
    • Endpoint Content Type - The content type expected from the specified endpoint URL. One of: JSON, RSS, XML, URL Encoded JSON, CSV, Text, or Twitter Encoded JSON.
    • Endpoint Method - One of:
      • GET - Specifies an HTTP Request GET method for the task field.
      • POST - Specifies an HTTP Request POST method for the task field.
    • Response Path - The path in the response that contains the desired drop-down list values, for example, data.
    • Label Key - The key for the label of the drop-down option, for example, name.
    • Option Value Key - The key for the value of the drop-down option, for example, id.
    • Editable - Enables the end-user to enter text free-from in the field as an option when type-ahead search results do not match.
  • Email - Displays a text box for the end-user to input an email address. In the Placeholder field, enter the help hint to display to the end-user inside the text box.
  • Date & Time - Displays a text box for the end-user to input a date with time. In the Format field, enter the expected date or time format to display to the end-user in the date text box. In the Select Date Format drop-down list, select the date with time format.
  • Time Zone - Displays a drop-down list of time zones based on the operating system settings.
  • Location - Displays a text box for the end-user to enter a geographical location, for example, Orlando, FL, or 32801.
  • Search Control - Displays a text box for the end-user to enter one or more search terms with dynamically populated search results as the user types. Define the following properties for a dynamically populated dropdown.
    • Endpoint URL - The Bot endpoint URL, for example, https://app.asana.com/api/1.0/workspaces.
    • Endpoint Content Type - The content type expected from the specified endpoint URL. One of: JSON, RSS, XML, URL Encoded JSON, CSV, Text, or Twitter Encoded JSON.
    • Endpoint Method - One of:
      • GET - Specifies an HTTP Request GET method for the task field.
      • POST - Specifies an HTTP Request POST method for the task field.
    • Response Path - The path in the response that contains the desired drop-down list values, for example, data.
    • Label Key - The key for the label of the drop-down option, for example, name.
    • Option Value Key - The key for the value of the drop-down option, for example, id.
  • Nested Form - Displays end-user input fields in a nested format below the parent input field. Specify the following fields for a nested form input field:
    • Array Element Type - Select the data type of the parent input form element.
    • Add Nested Form Field - Click to add one or more nested form fields.
  • File Upload - Displays end-user control to search for, and select a file to upload.
Data Type  The end-user input data type expected. One of:
  • String - The end-user can input any sequence of numbers, letters, or special characters.
  • Number - The end-user can only input digits 0-9. No special characters are allowed.
  • Boolean - The end-user can only input a Boolean value of true or false.
  • Object - Data from a Bot can be received as JSON objects, for example, as location details defined as:

     "location" : {

                   "lat" : 17.4374614,

                   "lng" : 78.4482878

                }

    where you can refer to the properties in a request chain or action request as location.lat, and location.lng.
  • Array - The end-user can pass a comma-separated list of values to the Bot. For example, in Google Calendar, multiple attendees with data can be passed as:
    "attendees": ["user1", "user2", "user3"]
    When selected, specify the Type for the end-user input as one of:
    • String
    • Number
    • Boolean
    • Object
    • Array
    • Date
  • Date - The end-user can enter or use a date picker control to provide a calendar date value.
Is Multi Select Select to enable this control to allow end-user input of more than one selection or entry.
Visibility Specify if the task input field should be visible or hidden from the end-user. If the field must be hidden, select Hidden. The default is Static (visible).
Depends On Defines a dependent task input field, for example, a project field may be dependent on a workspace field.
Mandatory Select if the end-user must define this setting to save the task settings configuration.

Click Add & Continue to save the task field for the task request and create another task field, or click Add & Exit to save the task field for the task request and close the dialog.

For multiple task input fields, you should order the task fields in the order the end-user should input values as shown in the following illustration.

For example, your end-user may need to select dates for report, and then choose a line item from that report. Use the Move Up  icon and the Move Down  icon in the Actions column in the Task Field(s) section to reorder the task fields if needed.

Click the Edit  icon to modify the settings for an existing task field.

Click the Delete  icon to delete an existing task field. 

Warning: No confirmation dialog is displayed when deleting a task field. If you click Continue or Save, the delete task is permanent and cannot be undone.

Setting Up an Action Task Request Object

In the Create Request Chain Object(s) section, you will add one or more request URLs and paths to your Bot to initiate the delivery of the data payload from the web service. Click Add Basic Request Chain Object to display the Set up Request Chain Object dialog as shown in the following illustration.

In the Set up Request Chain Object dialog, define the following parameters:

  • Post URL - The Post URL for the Bot specifies the endpoint for the task to be created, for example, https://api.twitter.com/1.1/friendships/create.json?follow=true
  • Content-type - Set to the communication type expected for the Bot web service. One of:
    • JSON - JavaScript Object Notation is an open standard format using human-readable text to transmit data objects as attribute–value pairs. You can use JSON to transmit data between the Kore servers and your Bot web application. 
    • RSS - Rich Site Summary, or Really Simple Syndication, is family of standardized formats used to publish frequently updated information such as blog entries, news headlines, audio, and video.
    • XML - Extensible Markup Language is a markup language that defines a set of rules for encoding documents in a format which is both human-readable and machine-readable. Oftentimes, Web Services use XML schemas to process the XML data.
    • URL Encoded JSON - URLs using JSON encoding for reserved characters.
    • CSV - Comma-separated value lists.
    • Text - Text-based key value pairs.
    • Twitter Encoded JSON - URLs for Twitter using JSON encoding for reserved characters.
  • Method - Set to the HTTP method used for the action. One of:
    • POST - Used to send data to the server, for example, customer information, file upload, and so forth using HTML forms.
    • PUT - Replaces the content of the target resource with the content sent.
    • PATCH - Appends the content of an existing target resource with the content sent.
    • DELETE - Deletes the content of an existing target resource.
    • GET - Returns the content of an existing target resource.
  • Access Using Connector - Select to enable access for Kore Bots using the Kore Connector agent. This option is only visible if a Kore Connector agent is configured and enabled in your enterprise on-premises network. For more information, see Using the Kore Connector.
  • Output Variable - Specify a variable name for the payload response, if needed, for example, when the payload does not contain a key for the payload response data.
  • Processors - You may need more than one request object to get the desired data payload from your web service. Select one of the following Type of Process option to collect, filter, or append to your data payload:
    • Resolve - To use the results of one payload response as input for a second request. For example, set Type of Process to resolve, Key to tasks, defining the Request URL using a variable from the first request (https://app.asana.com/api/1.0/projects/{project_id}) that returns the id field in the payload response as:

      {
      ....

      "id": 80468818418144,
      "created_at": "2016-01-14T05:34:35.848Z",
      "modified_at": "2016-01-20T04:29:52.505Z",
      "owner": {
      "id": 73114591129714,
      "name": "jaganmohan.evuri"
      },
      ...

      used as a variable input as shown in the following URL:

      https://app.asana.com/api/1.0/projects/{id}/tasks?opt_fields=completed,modified_at

    • Spread - For payloads that contain arrays of data that you need to separate into separate posts for the end-user.
    • Extract - For payloads that contain multiple objects, you can specify a path to the specific object. For example, set Key to data, and Type of Process to extract to use the object data in the following payload response.

      {
      "user": {
      "full_name": "Kore Hyd",
      "id": "2056218675",
      "profile_picture": "https://instagramimages-a.akamaihd.net/profiles/anonymousUser.jpg",
      "username": "kore_hyd"
      },
        ...
      },
      "likes": {
      "data": [
      {
      "full_name": "kstream002",
      "id": "2100724876",
      "profile_picture": "https://instagramimages-a.akamaihd.net/profiles/anonymousUser.jpg",
      "username": "kstream002"
      }
      },
        ...
      }

Click Add to save the request chain object and then create another, or click Add & Exit to save the request chain object and close the dialog.

For multiple request chain objects, you should order the requests in sequential order needed to get to entire data response. For example, you may need to request a list of workspaces, then a list of projects, and finally, a list of users. Use the Move Up  icon and the Move Down  icon in the Actions column in the Request Chain(s) section to reorder the request chain objects if needed.

For example, if your data is based on a project, then a workspace, and then a task. Use the Move Up  icon and the Move Down  icon in the Actions column in the Request Chain(s) section to reorder the request chain objects if needed.

Click the Edit  icon to modify the settings for an existing request chain.

Click the Delete  icon to delete an existing request chain. 

Warning: No confirmation dialog is displayed when deleting a request chain. If you click Continue or Save, the delete action is permanent and cannot be undone.

Adding Sample Response Data

In the Sample Response Data field, enter or paste examples of the key value pairs that you expect to receive in the payload for your task responses. When you define the sample response, the keys specified in the Sample Response Data text area are available as drop-down choices for handling the data in the task response from the Bot.

To format the view of the response as a JSON structure with indentation as shown in the previous illustration, click the Formatted  icon.

To format the view of the response in serialized compact form as shown in the following illustration, click the Unformatted  icon.

Next Steps

After you finish defining your task request object, click Continue to display the Configure Response Object for your Task dialog. For more information, see Configuring the Action Task Response.

Comments