Overview

Teams regularly need to perform a task or a set of tasks in multiple different stories. For example, a threat intelligence story and a phishing response story may use the same procedure to analyse a URL, similarly a user de-provision story and a vulnerability management story may require the creation of a Jira ticket.

Rather than creating the same set of agents in multiple stories (thus violating the DRY-principle), send to story allows users create “sub-stories” to which events can be sent from other stories. When an event is received by a sub-story, the sub-story will perform its action and when finished, emit an event from the calling agent.

Sub-stories

Sub-stories work the exact same as normal Tines stories. The only difference being that a sub-story has an Entry agent and an Exit agent. The entry agent must be a webhook type agent and the exit agent must be a message-only mode event transformation agent.

Enabling a story for send to story (creating a sub-story)

From a storyboard, when no agents are selected, in the properties panel there is a checkbox to enable a story for send to story, when this checkbox is clicked, you’ll be asked to specify entry and exit agents. A sub-story can only have one entry and one exit agent.

Enable sub-story from storyboard
Enable sub-story from storyboard
Configure send to story
Configure send to story

Entry agent

When an event is sent to a sub-story, the entry agent will emit an event to its receiver agents. Entry agents must be of type Webhook.

Exit Agent

The Exit agent is the last agent in a sub-story and must be a message-only mode event transformation agent. The content specified in the Exit agent will be emitted by the agent that originally sent the event to the sub-story.

Agent event flow from Sample sub-story showing entry and exit agents.

Sending to a sub story

When you need to send data to a sub-story, you should use a Send to Story Agent with the story widget. For example say we have a sub-story called Substory we would send events to this sub-story with the following HTTP Request Agent:

{
  "story": "{% story Substory %}",
  "payload": {
    "url": "http://evil-site.com"
  }
}

The entry agent in Substory will then emit an event similar to the below:

{
  "receive_url_to_analsye": {
    "url": "http://evil-site.com",
    "#event_id": "1029",
    "#agent_id": "21"
  }
}

When this event has run down the story, an event will be emitted at the calling Send to Story agent that matches the exit agent’s configuration.

For example, let’s say the HTTP Request Agent above was named “Analyse URL” and we have the following exit agent defined in Substory:

{
  "mode": "message_only",
  "uppercase_url": "{{.receive_url_to_analsye.url | upcase }}",
  "expected_update_period_in_days": "2"
}

When the sub-story is complete Analyse URL will emit an event similar to the below:

{
  "analyse_url": {
    "uppercase_url": "HTTP://EVIL-SITE.COM"
  }
}