Send to Story

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 analyze 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 actions 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 action.

❗️Important

Sub-stories​ 

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

Enabling a story for Send to Story (creating a sub-story)​ 

From a storyboard, when no actions 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 actions. A sub-story can only have one entry and one Exit action. 

Entry action​ 

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

Exit actions​ 

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

Access​ 

Controls who is allowed to send to this story. Either select everyone to allow any team send to this story, or select the team that owns the story to restrict access.

Sending to a sub story​ 

When you need to send data to a sub-story, you should use a Send to Story action with the STORY key in formulas. For example say we have a sub-story called Substory we would send events to this sub-story with the following Send to Story action:

{
  "story": "<<STORY.substory_name>>",
  "payload": {
    "url": "http://example.com"
  }
}

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

{
  "receive_url_to_analyze": {
    "url": "http://example.com",
    "#event_id": "1029",
    "#action_id": "21"
  }
}

When this event has run down the story, an event will be emitted at the calling Send to Story action that matches the Exit action's configuration.

For example, let's say the HTTP Request action above was named "analyze URL" and we have the following Exit action defined in Substory:

{
  "mode": "message_only",
  "uppercase_url": "<<UPCASE(receive_url_to_analyze.url)>>"
}

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

{
  "analyze_url": {
    "uppercase_url": "HTTP://EXAMPLE.COM"
  }
}

Retrieving event data from Story runs using Send to Story 

Using Send to Story it is possible to make a HTTP request to initiate a Story run and receive event data back from the Story. This can be configured via Send to Story settings:

Retrieving data can be achieved by making a HTTP request to the webhook Entry action, check out our Webhook Action lesson for more information on this.

The endpoint will return the event data emitted by the Exit action. For example:

HTTP/1.1 200 OK

{ 
    "message":"The random number is: 4"
}

In the case where there are multiple Exit actions, the event data from first Exit action to execute will be returned.

Response Body, Status and Headers 

By default, the payload of the Exit action is returned in the webhook HTTP response body. You can gain more fine-grained control over the response by adopting an Exit action payload convention.

If your Exit action contains the status and body keys and the status field is a valid HTTP response code the status field will be used to set the HTTP status line and the body field will be used as the HTTP response body.

Furthermore, you can include a headers object to include custom HTTP response headers. For example, the following exit action payload will generate the HTTP response below.

{
  "status": "202",
  "headers": {
    "X-Tines-Story": "<<META.story.name>>",
    "X-Tines-Change-Control-Test": "<<META.story.is_test>>"
  },
  "body": {
    "random_number": "The generated random number is <<generate_random_number.number>>"
  }
}
HTTP/1.1 202 Accepted
X-Tines-Story: My Story
X-Tines-Change-Control-Test: true

{ 
    "random_number":"The generated random number is 4"
}

Metadata 

Included in the response will be a set of HTTP headers containing metadata about the status of the request, the event and the action producing the data:

  • X-Tines-Status: The status of the request, values include:

    • data_received - the story executed and data is included in the response.

    • ok - the story is executing but did not return data in time.

    • error - there was an error processing the request.

  • X-Tines-Event-ID: The ID of the event containing the data that was returned.

  • X-Tines-Exit-Action-ID: The ID of the Exit action that produced the event.

  • X-Tines-Exit-Action-Name: The Name of the Exit action that produced the event.

  • X-Tines-Limit-Reached: If the request reached a limit the limit that was reached will be included here.

Limits 

There are limits on how much this feature can be used. In order to return data in a timely manner story runs must complete within 10 seconds.

Stories executed this way are guaranteed to run, so even if your Story run does not complete within 10 seconds it will be executed to completion. In these cases a response of HTTP/1.1 201 Created will be returned, rather than a 200 status code.

HTTP/1.1 201 Created

{ 
    "status": "ok"
}

There are also limits on the number of these requests that can be run simultaneously. In the cases where these limits are exceeded a response of HTTP/1.1 201 Created will be returned, rather than a 200 status code, and the story will continue to run.

More information is included in the X-Tines-Status and X-Tines-Limit-Reached HTTP headers.

Was this helpful?