Configuring the Response Object for an Alert Task

After you define the request objects for your alert task, you must decide how to display the task payload response to the end-user, for example, for a Twitter task, you probably want to show the name of the new follower, along with the tweet. This topic describes how to define the response object for an alert task. 

The following illustration is an example of the Configure the Alert Task Response dialog.

Defining the Task Response Object

To define a task response object, there are five basic sections:

  • Filters - Depending on how you define your request object, a large amount of data can be received. You can define one or more Filters to allow an end-user to refine the results to a specific subset of data.
  • Deduplicate Strategy - You may need to specify an option to prevent duplication of data results displayed in the response object, for example, for Twitter posts, or RSS feeds. This setting is only available for web service and RSS tasks Connection Type.
  • Post Title - When the response object displays the data in the payload response in Kore for the end-user, you must define the Post Title of the message, usually, a well-formed HTML message that contains one or more variables, such as the ID number or subject, from the request object data.
  • Post Description - The Post Description contains the body content of the data from the request object in the Kore message displayed to the end-user. The description is defined as a well-formed HTML message that may contain one or more dynamic variables to display the content of the task payload.
  • Additional Information - For some tasks, you may want to display 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. Use Additional Information when the payload data contains a large amount of data, for example, a list of contacts, that the end-user can request on-demand using the link.

 To get started, you may want to define optional Filters for your end-users.

Defining Alert Task Filters

In the Filters section of the Configure the Alert Task Response dialog, click Add Filter if you want to define one or more filters for your end-users to configure. The Alert Task Filter dialog is displayed as shown in the following illustration.

The Filter defined in the previous illustration is displayed to the end-user as a filter labeled Notify me only when the below user tweets, with the Field Type set to Type Ahead to enable the end-user to define search terms to filter the data returned in the response payload as shown in the following illustration.

To create a new filter, in the Filter section, click Add Filter. The Alert Task Filter dialog is displayed. Define the fields described in the following table to create a new filter for a task.

Field NameDescription
Name Specify the name of the Filter displayed to the end-user in Filters section when configuring the task. In the previous illustration, the Name is Notify me only when the below user tweets.
Field Name

Enter the name of field to filter the task on, or click Select Field to display a drop-down list of field names parsed from the Sample Response Data defined in the task request object as shown in the following illustration.

Field Type Specifies the type of filter input field displayed in the end-user interface to collect user input. One of: 
  • Textbox - Displays a text box for the end-user to enter text as the filter, 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.
  • Textarea - Displays a text area box for the end-user to enter text as the filter, typically for several sentences. In the Placeholder field, enter the help hint displayed inside the text area.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
    • Box Value Key - The key for the value of the checkbox option, for example, id.
Data Type The data type for the content received from the endpoint URL. One of:
  • Text - The user input for this filter is expected as text.
  • Number - The user input for this filter is expected as an integer.
  • Date - The user input for this filter is a date.
  • List - The user input for this filter is a comma separated list.
Operators Select one or more filter operations that the end-user can select to apply to the filter. Depending on the Data Type selected, one or more of the following options are available to select to display to the end-user in the filter.
  • Contains - The response object filtered text contains all of the specified values.
  • Doesn't Contain - The response object filtered text does not contain all of the specified values.
  • Exact Match - The response object filtered text only contains the specified values.
  • Not an exact match - The response filtered text object does not contain the specified value.
  • Included - The response object filtered text contains any of the specified values.
  • Not Included - The response object filtered text does not contain any of the specified values.
  • Starts with - The response object filtered text begins with the specified value.
  • Doesn't start with - The response object filtered text does not begin with the specified value.
  • Ends with - The response object filtered text ends with the specified value.
  • Doesn't end with - The response object filtered text does not end with the specified value.
  • Equal to - The response object filtered numbers or dates are equal to the specified value.
  • Greater than - The response object filtered numbers or dates are greater than the specified value.
  • Less than - The response object filtered numbers or dates are less than the specified value.
  • Exists - The response object filtered list contains the specified value.
  • Doesn't exist - The response object filter list does not contain the specified value.

Preventing Duplicate Message Notifications

After you add your filters for the response object, you should determine if you need to apply a strategy to prevent duplicate notification messages. For example, if you set up an RSS task, you may want to prevent duplicate messages for the same subject, or for Facebook, prevent notifications for each comment to a post.

Note: These settings are not necessary or available for webhook tasks.

In Kore, you can choose one of three options for Deduplicate Strategy:

  • None - This is the default method to prevent duplicate notification messages. Each incoming task payload is hashed and the latest 500 task hash values are persisted. Each new task payload is compared against the list to prevent duplicate task notification messages.
  • SinceID - Select this option for task response payloads that are reversed chronologically and sorted based on the timestamp in the payload response. You must define a unique identifier key in each task payload for sorting. For each task poll, the most recent value of the unique identifier key is persisted and evaluated against each subsequent notification message. Only notification messages after the timestamp value are accepted.
  • ExcludeByCachedIds - Select to enter one or more response identifier keys in a comma-separated list used to filter Kore task notification messages and prevent duplication based on the cached hash value of the key for up to 500 hash values. If any of the key hash values match the response object, then the notification message is filtered and not displayed. For RSS Alert Types, RSS XML payloads are parsed as JSON. To filter by RSS item, enter $..guid[0]._ to prevent duplicate notification messages using the XML <guid> tag parsed to JSON as:

     "guid" : [
       "_" : "some link"
     ]

Defining the Post Title and Post Description

Now that the task filters and duplication prevention objects are in place, you are ready to define how the notification message is displayed to the end-user. In Kore, notification messages are delivered and displayed on the Bots tab on the  Messages page as shown in the following illustration.

In the previous illustration, for the Weather Updates message notification, the Post Title is displayed below the task name in the left column, and also in the right column for detailed information, along with the Post Description.

Using the Response Object Editor

The Response Object editor has three interrelated tabs that you can use to define your response object for your task. 

The Normal tab is used to formulate the message notification displayed in the end-user interface using basic editor controls and HTML. You can enter text, and then format the text using the formatting buttons for bold, italics, and underline. In the Select any key drop-down list, you can choose to insert variables parsed from the Sample Response field defined in the request object, or any variables declared on the Java Script tab as shown in the following illustration for the prefix, link, and action variables added on the Normal tab.

To add a variable, place the cursor where you want to add the response key or variable, and the in the select any key drop-down list, select the object that you want to add as shown in the following illustration.

On the Java Script tab, you can add code to handle the end-user message notification, declare variables, and interact with third-party applications.

For the task described in the previous illustration, the following JavaScript is added to the Java Script tab to define four variables, and to verify updates.

var linkLabel = Id;
if (Name)
   linkLabel = Name;
var link = '<a href="https://login.salesforce.com/' + Id + '" target="_blank">' + linkLabel + '</a>';

var prefix = 'New Opportunity';
var action = 'created';

if (CreatedDate !== LastModifiedDate) {
   prefix = 'Opportunity';
   action = 'updated';
}

By combining the objects defined on the Java Script tab, with the static text and variables added on the Normal tab, you can create the title of the post to, for example, contain a link from the message notification in the Kore application directly back to the web application.

On the Preview tab, you can view a sample of the rendered output message that is displayed to the end-user for the Sample Response data you added in the request object, as shown in the following illustration for a Post Title.

Examples

The following examples show response objects using Java Script to define the Post Title and Post Description sections that display output messages to the end-user when the task notification message is sent.

In the following example, the variable labeled desc is only displayed if the value for 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 notification message.

var tasklink = '<a href="https://www.wunderlist.com/webapp#/tasks/' + id + '" target="_blank">' + title + '</a>';

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 script to handle task-specific requirements on the Java Script tab in the response object for the task.

Adding Additional Information

Click the Add Additional Information  icon to display the configuration parameters for adding a link to a report as part of the end-user response as shown in the following illustration. 

 

Define the following parameters for the additional information:

  • Link Title - The link text displayed to the end-user in the task post.
  • Header - The title displayed when the report is displayed to the end-user.
  • Details - End-user help information displayed directly below the Header in the report that describes the content of the report.
  • 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.
    • 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 fixedDisplay as an image, and Display it as a link.
    • 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.
    • 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.

Next Steps

After you configure the response object for your alert task, depending on the Alert Task Type, you may also need to configure alert task settings. For more information, see Alert Task Settings.

Comments