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 name.

Usage: {% credential USER_CREDENTIAL_NAME %}.

The credential name is case sensitive and must match the stored user credential name exactly. Further details on user credentials is available in the user credentials section.

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.)

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."
  },
  "expected_update_period_in_days": "1"
}

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 }}"
    }
  ],
  "expected_update_period_in_days": "2"
}

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 inadvertant 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