Overview
While building in Tines, you'll come to find that there are many ways to build out a story that aren't so linear. A story fork is a design pattern that typically includes multiple streams of actions that stem from one "kickoff" action, that then pull back together to continue the story as a singular flow. Story forks make building convenient and easy, both from a processing perspective and a visual perspective.
Tines references
Before getting started, we recommend familiarizing yourself with the surrounding functionality this article covers:
Tines - Stories
Tines - HTTP Request Action
Make it happen
Step One: Map an HTTP request
We prepare our HTTP request by mapping out the URL, selecting the appropriate method (GET, POST, etc.), and specifying any necessary parameters. This ensures that the request is well-structured. Let's look at an example of an API endpoint that doesn't require authentication (also known as an open API).
We have a Dungeons & Dragons service that 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 test out this API here: https://www.dnd5eapi.co/
If you enter that URL into your browser and press enter, you'll receive the same information as you would by using an HTTP request action. In the example our article covers here, we'll be using "https://www.dnd5eapi.co/api/spells." To use this URL in an HTTP request action, simply copy the URL and paste it into the URL section of the actions configuration.
Example Steps:
Add an HTTP request action.
Set the name.
Set the URL.
Retrieve the URL from the API documentation.
Set the content type to JSON.
Set the method to GET.
Most services that don't require authentication with a password or API token typically use GET by default.
Run the action to review the results in the event data.
This method applies to any API service you want to configure as an HTTP request.
Step Two: Capture data in an event transform action
When we fork a story, we often need to capture and organize data as it flows through various paths. The event transform action allows us to catch the incoming data and normalize it for consistent use downstream.
We continue the naming convention of "format" to ensure that subsequent actions reference the format.message field. This approach allows us to rely on the event transform to normalize the data, avoiding concerns about variations in the JSON paths across different HTTP request actions that occur beforehand.
Example Steps:
Go to the action you want to capture data from.
Go to the HTTP Request action (in this example).
Open the event data by clicking the number in the top right corner (e.g., 1).
Click the
[ ][ ]icon to the left of the value you want to map or copy.Add an event transform action.
Connect the previous action to the newly added event transform.
Set the name to "Format."
Click the purple text next to "message" in the builder.
Delete the purple text.
Press
CMD+Vto paste the data you copied earlier.Repeat this process for any other actions you want to map data for.
Tines Tip: You can copy an action with CMD+C and then paste it with CMD+V. This reduces the need to recreate the event transform action manually.
Step Three: Pull results together from different actions
Now we'll need to aggregate the results. This involves using the implode mode of the event transform action. The configuration includes specifying the size (number of items), determining the item path (which data elements to group), and using an identifier path to correctly pull the items together.
Example Steps:
Pull in an event transform action.
Set the name.
Set the mode to implode.
Set the item path:
These are the objects you want to pull together. So if you have an action named "Format" and inside of it an object named "message", then we would set the item path to "format.message".
Set the item size:
This is how many items you want to pull together in your list/array. Since this example has 2 items, we'll set the size to 2.
Set the identifier path:
This is when we want to pull the story together.
STORY_RUN_GUID()is great to leverage because it is a unique code generated every time you run a story.An alternative way is by going to the options on the bottom of the action and adding "seconds". If we do this we'll want to click the "-" to the right of identifier path and just use the seconds instead. Selecting how long to wait to pull together results.
Review the results
Now you can run the story from the top and see how the story fork works into the implode.