Tines provides a number of action helper widgets which can be used in action options blocks.

Credential Widget

The credential widget allows users store sensitive information in action 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.

Resource Widget

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

Usage: {{ .RESOURCE.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. Resources created as JSON or Array data structures can have their data elements accessed like {{ .RESOURCE.resource_slug.key }} or {{.RESOURCE.resource_slug[0]}} respectively.

In some situations such as sending or modifying data, it is necessary to cast the resource to an object using the as_object Liquid filter (ex. {{ .RESOURCE.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 action’s options block it will convert to a URL with the below format at run-time: https://<tenant-domain>/prompt?e=<event_id>&a=<action_id>&s=<STATUS_STRING>

The above placeholders will be replaced as follows:

  • <event_id> will be replaced with the incoming event’s id.
  • <action_id> will be replaced with the action (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 Actions. Shown below is a sample options block for a HTTP Request Action 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 action 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 action 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": {
    "action_id": "10",
    "event_id": "243",
    "status": "here"
  }
}

These events can be received and further processed by downstream actions. For example, as below, a Trigger Action could be used to emit events when a prompt was present in events emitted by an email action 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 action, the story widget can be used to select the correct story. When selecting the story, the user must first select the team from the suggested options followed by the story name.

Using the Story widget

Story Run Widgets

Story Run Link

When an action 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 action 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 action 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.