Overview
While building in Tines, you'll find that there are many ways to structure a story beyond a linear flow. A story fork is a design pattern where multiple streams of actions branch out from a single "kickoff" action, process in parallel, and then come back together to continue as a singular flow. Story forks are useful both from a processing perspective (running tasks simultaneously) and a visual perspective (keeping your storyboard organized).
Tines references
Before getting started, we recommend familiarizing yourself with the functionality this article covers:
Make it happen
Map an HTTP Request
We prepare our HTTP Request by identifying the URL, selecting the appropriate method (GET, POST, etc.), and specifying any necessary parameters. Let's look at an example using an API that doesn't require authentication (also known as an open API).
The Dungeons and Dragons 5e API lets us request information about spells, classes, and monsters. You can ask for the entire list of spells or retrieve a specific one like "acid-arrow." You can explore this API here: https://www.dnd5eapi.co/
If you enter that URL into your browser, you'll receive the same information as you would from an HTTP Request action. In this example, we'll use https://www.dnd5eapi.co/api/spells.
To use this URL in an HTTP Request action, copy the URL and paste it into the URL field in the action's configuration. This approach applies to any API you want to call from an HTTP Request action.
In this video, we walk through setting up an HTTP Request action.
Example steps:
Add an HTTP Request action.
Set the name.
Set the URL. Retrieve this from the API's documentation.
Set the content type to JSON.
Set the method to GET. Most open APIs that don't require authentication use GET for retrieving data.
Run the action and review the results in the event data.
This approach applies to any API you want to call from an HTTP Request action.
Capture data in an Event Transform action
When you fork a story, you often need to capture and organize data as it flows through each branch. The Event Transform action lets you catch the incoming data and normalize it for consistent use downstream.
In this video, we walk through formatting event data with an Event Transform action.
We use the naming convention "Format" to ensure that subsequent actions reference the format.message field. This approach lets you rely on the Event Transform action to normalize the data, so you don't need to worry about variations in the JSON paths across different HTTP Request actions that occur beforehand.
Example steps:
Open the event data from the HTTP Request action you want to capture data from.
Copy the path to the value you need.
Add an Event Transform action and connect it to the HTTP Request action.
Set the name to "Format."
Paste the copied path into the message field.
Repeat for the other branch.
Tines tip: You can copy an action with CMD+C (or Ctrl+C on Windows) and paste it with CMD+V (or Ctrl+V on Windows). This saves time when you need the same action structure on multiple branches.
Pull results together with implode
Now we need to aggregate the results from both branches back into a single event. This is where the implode mode of the Event Transform action comes in.
Implode collects individual events and combines them into one. You configure it by specifying:
Item path. The data you want to collect from each incoming event. If each branch has an action named "Format" with a value in
message, set the item path toformat.message.Size. The number of items to collect before emitting. Since this example has two branches, set the size to
2.Identifier path. How implode knows which events belong together.
STORY_RUN_GUID()works well here because it generates a unique identifier for each story run, ensuring that only events from the same run are combined.
In this video, we walk through combining results with implode.
Example steps:
Add an Event Transform action and connect both branches to it.
Set the name.
Set the mode to
implode.Set the item path to the data you want to collect.
Set the size to the number of branches (in this case,
2).Set the identifier path to
STORY_RUN_GUID().
As an alternative to using an identifier path, you can add a seconds option via the + Option button at the bottom of the action. This tells implode to wait a set number of seconds after receiving the first event before emitting. If you use seconds, remove the identifier path.
Review the results
Run the story from the top and watch how the two branches process in parallel before the Implode action combines their results into a single event. This pattern is useful any time you need to gather data from multiple sources simultaneously and then continue processing it as one unit.