Widgets

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

Credential Widget 

The credential widget allows users to store sensitive information in action options blocks without the need to insert the information in plaintext. The credential widget returns the stored 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 access to 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 }}).

Meta Widget 

The meta widget allows access to information about the current environment, like the name of the current team or the ID of the current action.

Usage: {{ .META.team.name }}.

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.

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

💡Note

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.

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.

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 %}"
}

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 %}"
}
Was this helpful?