Agents are configured using a “Common Config” and an “Options block”. When creating and editing agents a page displaying both configurations is presented:

Agent configuration options
Agent configuration options

Common Config

All six agent types have a set of configuration options that describe the basic operation of the agent, this is known as the agent’s Common Config, a description of options included in the common config is shown below.

Name: Provide a name for the agent.

Story: Specify the story for the agent. Agents can only be in one story and can only send to, and receive from, agents in the same story.

Schedule: Depending on the agent type, specify when the agent should run.

Keep events: Specify how long events should be retained in Tines. When this period lapses, events will be purged.

Sources: Define one or more agents that this agent should receive emitted events from. Source agents must be in the same story.

Receivers: Define one or more agents that this agent should emit events to. Receiver agents must be in the same story.

Depending on the agent type, all options may not be available in the common config. See the below table for a description of the availability of “Schedule”, “Sources”, and “Receivers”.

Agent Type Can be Scheduled Can Receive Events Can Emit Events
Email Agent No Yes Yes
Event Transformation Agent No Yes Yes
HTTP Request Agent Yes Yes Yes
IMAP Agent Yes No Yes
Trigger Agent No Yes Yes
Webhook Agent No No Yes

Options Block

The options block defines the exact action an agent should perform at run-time and is unique to each agent type. The options block is a JSON object which consists of key/value pairs. Information from incoming events can be referenced in an agent’s options block by including “wrapped JSONPaths”. Shown below is an example of an options block from an Email Agent. For detailed instructions covering the configuration of options blocks, see individual articles on Agent Types.

{
  "recipients": "{{.recipient.emailAddress}}",
  "subject": "New Tines alert",
  "body": "Malicious behaviour has been detected.",
  "expected_update_period_in_days": "2"
}

Working with Events and JSONPaths

Every Tines event is a JSON object. The data within Tines events can be accessed in agent configurations using JSONPaths.

{
  "customerName":"John Doe",
  "address":
  {
    "streetAddress":
    {
      "number":123,
      "street":"AnyStreet"
    },
    "city":"Anytown"
  }
  "orders":
  [
    { 
      "orderId":23284, 
      "itemName":"Widget", 
      "itemPrice":33.99 
    },
    { 
      "orderId":63122, 
      "itemName":"Gadget", 
      "itemPrice":22.50 
    },
    { 
      "orderId":77284, 
      "itemName":"Sprocket", 
      "itemPrice":12.00 
    }
  ]
}

To insert information from an incoming event into an agent’s options block, use the following syntax. Here, keyname is the name of the key to insert.

{{ .keyname }}

The following wrapped JSONPath will insert the value of the customerName key from the above, sample Tines event.

{{ .customerName }}

John Doe

To access information in a nested JSON key, use the following syntax:

{{ .keyname.subkeyname }}

The following wrapped JSONPath will insert the value of the city key from the above, sample Tines event.

{{ .address.city }}

Anytown

Accessing Data in Nested Keys

You can query further levels of subkeys using the following syntax.

{{ .address.streetAddress.street }}

AnyStreet

Accessing Data in Arrays

Arrays are queried using an array index expression inside square brackets ([]). For example, the following wrapped JSONPath can be used to access the first element of the “orders” array:

{{ .orders[0] }}

{ 
  "orderId":23284, 
  "itemName":"Widget", 
  "itemPrice":33.99 
}

The following wrapped JSONPath will return the itemPrice from the 2nd element of the orders array.

{{ .orders[1].itemPrice }}

{ 
  "orderId":63122, 
  "itemName":"Gadget", 
  "itemPrice":22.50 
}

API Autocomplete

When editing or creating an agent, ‘API Autocomplete’ allows you to more easily define JSONPaths in the options block. In an options block, when a period is entered between two sets of curly braces, Tines will provide a list of available keys from the most recent event emitted by the defined source agent(s). When a key is selected and another period is pressed, Tines will present the keys from the most recent event at that level.

API Autocomplete in options block
API Autocomplete in options block