Tines provides a number of Agent Helper Widgets which can be used in Agent options blocks.

Credential Widget

The credential widget allows users store sensitive information in Agent options blocks without the need to insert the information in plaintext. The credential widget returns the stored user credential for the given credential slug.

Usage: {{ .CREDENTIAL.user_credential_slug }}.

The slug is an underscored representation of the credential name. For example, a credential named “My Credential” has a slug of my_credential.

Global Resource Widget

The global resource widget allows users access information stored in resources. The global resource widget returns the stored information for the given slug.

Usage: {{ .RESOURCE.global_resource_slug }}.

The slug is an underscored representation of the resource name. For example, a resource named “My Resource” has a slug of my_resource. Global resources created as JSON or Array data structures can have their data elements accessed like {{ .RESOURCE.global_resource_slug.key }} or {{.RESOURCE.global_resource_slug[0]}} respectively.

In some situations such as sending or modifying data, it is necessary to cast the global resource to an object using the as_object Liquid filter (ex. {{ .RESOURCE.global_resource.slug | as_object }}).

Line Break Widget

The line break widget converts to a literal line break in the text at run-time, i.e. a “\n” character.

Usage: {% line_break %}

Note that there are no quotes or back ticks around the tag. (Note: for HTML emails, you may want to use <br> instead.)

Random Number Widget

The random number widget converts to a random integer number in a specified range. A new number is generated for each event emitted. When a single number is specified then the widget will convert to a number between 0 and the specified number (inclusive).

Usage: {% random 50 %}

When a range is specified (2 numbers separated by a -), the widget will convert to a number between the 2 numbers (inclusive).

Usage: {% random 60-180 %}

Prompt Widget

The prompt widget provides a mechanism to automate response collection from users.

Usage: {% prompt STATUS_STRING %}

When a prompt widget is used in an agent’s options block it will convert to a URL with the below format at run-time: https://<tenant-name>.tines.io/prompt?e=<event_id>&a=<agent_id>&s=<STATUS_STRING>

The above placeholders will be replaced as follows:

  • <event_id> will be replaced with the incoming event’s id.
  • <agent_id> will be replaced with the agent (containing the prompt) id.
  • <STATUS_STRING> will be replaced with the string defined in the prompt widget.

Prompt widgets will typically be used in Email and HTTP Request Agents. Shown below is a sample options block for a HTTP Request Agent posting a message to Slack with a prompt.

{
  "url": "https://hooks.slack.com/services/T9GT9GT9G/G6Dx5ceVyR/S7QzeA7GLR0HN9fTKKLo",
  "content_type": "json",
  "method": "post",
  "payload": {
    "text": "Click <{% prompt here %}> to confirm."
  }
}

The above agent will produce a Slack message that looks like the below:

Slack message with prompt
Slack message with prompt

When a user clicks this link they will be presented with the below screen:

Prompt response confirmed page

Handling Prompt Responses

When a prompt link is clicked, a new event will be emitted by the agent configured with the prompt widget. The details of the prompt will be included in the new event in an object called prompt (sample below).

{
  "prompt": {
    "agent_id": "10",
    "event_id": "243",
    "status": "here"
  }
}

These events can be received and further processed by downstream agents. For example, as below, a Trigger Agent could be used to emit events when a prompt was present in events emitted by an email agent called “Send email with prompt”.

{
  "rules": [
    {
      "type": "regex",
      "value": "prompt",
      "path": "{{ .send_email_with_prompt }}"
    }
  ]
}

If a prompt link is clicked, but the incoming event which triggered the prompt has expired, the user will receive a 404 error and no event will be emitted.

Preventing Automated Prompt Responses

To identify malicious URLs, it is common for security tools to “click” links and examine the resultant pages. Where prompt links are involved, this may result in inadvertent prompt responses.

To prevent this, Tines supports a two-step, captcha-protected prompt page. In this mode, Tines will display a page with a captcha-protected form asking the user to confirm their response before processing the prompt, see example below. To enable two-step prompts on your tenant, contact support@tines.io.

Two-step prompt confirmation page

Story Widget

When configuring a Send to Story agent, the story widget can be used to list all sub-stories available in the tenant.

Using the Story widget

Story Run Widgets

Story Run Link

When an agent containing the Story Run Link widget runs, a link corresponding to the exact story run will be generated. This allows users include clickable links to story runs in emails, tickets, Slack messages etc.

For example, when the following email agent runs, it will send an email that looks similar to the below

{
  "recipients": "alice@tines.xyz",
  "subject": "Red alert detected",
  "body": "Story run available here: {% story_run_link %}"
}
Emailing including link to a story run.

Story Run GUID

Similar to the Story Run Link, however, the Story Run GUID will only generate the corresponding GUID associated with the story run

For example, when the following email agent runs, it will send an email that looks similar to the below

{
  "recipients": "alice@tines.xyz",
  "subject": "Red alert detected",
  "body": "Story run available here: {% story_run_guid %}"
}
Emailing including GUID of a story run.