Playbooks User Documentation
| Purpose | For a deeper understanding of playbooks and their functionality, please refer to this documentation. This will be a helpful guide that explains everything in simple terms, so you can easily understand how playbooks work and what they can do for you. |
|---|
| Scope | This documentation contains vital information essential for users to create and make use of PLAYBOOKS. |
|---|
| Created | September 25, 2023 |
|---|
What are Playbooks?
Playbooks allow you to create automated workflows by dragging and dropping Brick Constructs into a canvas and connecting them together. Meaning they automate actions based on events.
What is the difference between Flows and Playbooks?
As you explore our documentation, you might notice that Playbooks and Flows seem similar at first glance. However, it's important to understand how they differ.
Flows are like data managers. They handle storing, organizing, and modifying data. Think of them as the behind-the-scenes workers that keep your data in order.
Playbooks, on the other hand, are more like action-takers. They respond to specific events based on conditions you set. For example, if you want to receive a slack notification whenever there is a new post on a website you are tracking, you would set up a Playbook.
So, in simple terms, Flows deal with data management, while Playbooks are all about taking action when something important happens with your data.
Types of Brick Constructs
Within Playbooks, the Raven Portal offers four Brick constructs:
Trigger: Triggers are events that initiate a playbook. They can be internal events, such as a scheduled time, or external events, such as a webhook. When a Trigger is activated, it starts the Playbook.
Triggers can be thought of as a special type of Action Brick that activates a Flow when certain conditions are met.
You can determine the category of the Trigger Brick by the red color assigned to it.
Operator: Operator Bricks determine how a Playbook flows. Think of them as the decision-makers of the Playbook. They are like inspectors set up at certain levels of the Playbook which check if the parameters set up by you are being followed. For example, you might configure an Operator Brick to examine incoming data and check if it meets specific criteria. If the data matches these criteria, the Operator Brick allows it to continue down a particular path, perhaps performing certain actions or transformations. On the other hand, if the data doesn't meet the criteria, the Operator Brick can reroute it or trigger different actions.
You can determine the category of the Operator Brick by the blue color assigned to it.
Transform: Transforms are used to modify data that is passed between actions. They can be used to filter data, add metadata, or perform calculations. Transforms are especially useful when working with data from multiple sources or when the data needs to be formatted in a specific way.
You can determine the category of the Transform Brick by the orange color assigned to it.
Action: Actions are tasks that are performed by the Playbook. They can be anything from sending an email to making an API call. Each action has specific inputs and outputs and can be customized to suit the needs of the Playbook.
You can determine the category of the Action Brick by the green color assigned to it.
Creating a new Playbook
To create a Playbook, select the Playbooks App. Once inside this section, you will be able to access existing Playbooks and also create new ones.
Click on the "NEW PLAYBOOK" button located at the top right corner to start your new Playbook.
This will open up a tab with three sections:
A left column containing the different Bricks available.
A canvas in the center.
A right column where you can add a title and description of the Playbook.
Add a title to save your Playbooks to avoid losing any progress.
Don't forget to save your Playbook to ensure you don't lose any changes you've made.
Playbooks can not handle more than one person editing them at the same time. So, if two or more people are working on them and try to save the information it will not be able to save the work correctly. For example, if person A saves the playbook while person B is still working on it, and a few minutes later person B also saves it it will override person's A edition.
Now that the Playbook is created, let's add some bricks to the canvas. Find your Bricks from the list on the left and drag and drop them on the canvas.
Once Bricks are added, you can configure them by selecting the Brick and providing the necessary information. You can also establish connections between Bricks by clicking on the output and dragging an arrow to the new Brick, creating an automated workflow.
At the top right corner, you will find some buttons with which you can interact:
Disable: This button will stop the Brick from running, turning the Brick grey.
Enable: This button will start running the Brick, returning it to its original color depending on the category of the brick.
Duplicate: Gives you an exact replica of the selected Brick. No configuration needed, it will just duplicate the selected Brick.
Delete: This action will remove the selected Brick.
Save: This action will save the Playbook.
Always remember to save the Playbook after any changes made.
Frequently Used Bricks
Forms (Trigger Brick)
This type of Bricks are used for triggering the Playbook manually.They work by connecting the output and dragging the arrow to the new Brick.
There are two ways of creating Forms. The first one is by going to the Form App and selecting the "ADD FORM" button. This will open a tab called "Form editor" where you can:
- Name the Form
- Add a description
- Incorporate different elements based on what the Form is meant to accomplish
To set up a Form, copy the URL shown on the pane that opens up when the brick is added and paste it into a new tab. Then, fill out the Form and save it to activate it.
The second way to configure Forms is by tasks, which is a way to set up Forms automatically from another software (like Python). You can add a task in two different ways, the first one would be by clicking on the three dotted button located at the top right corner of each Playbook in the main pane, the second way would be by adding "/tasks" after the webpage URL, for example:
https://raven.dtact.com/playbook/{Playbook_ID}/tasks
This will take you to a new tab showing:
- All tasks within the form
- Node where the task is located
- Status: Is the task running, paused or is there an error
- RunAt: Which tells when the task is supposed to run
- CreatedAt: Tells you when the task was created
- Search bar: Here you will be able to filter through the tasks by Brick type, status and Brick name.
By clicking on a specific task, you can see the progress of the tasks and subtasks. At the same time, next to the name of the task, we can see some icons which, when clicked, will show the configuration and data going through the tasks.
These tasks are very useful for debugging since they show what is happening in the Brick.
Forms can be shared with different users by sending the form URL.
Schedule (Trigger Brick)
You can schedule Playbooks to run at desired times. For this, add the schedule Brick to the canvas and configure it by specifying a schedule using cron, as illustrated below:
┌──────── minute (0 - 59)
│ ┌──────── hour (0 - 23)
│ │ ┌──────── day of the month (1 - 31)
│ │ │ ┌──────── month (1 - 12)
│ │ │ │ ┌──────── day of the week
│ │ │ │ │
│ │ │ │ │
If you do not know how to use cron, use the Prompt option, which is powered by ChatGPT. Here you can just write down when you want the Brick to run, for example:
Every first day of the month at 14.
This will automatically fill in the cron.
For more information about cron follow link below:
Webhook (Trigger Brick)
Is a Brick that uses an external software to trigger, defining the properties of objects coming in. In simpler words, it is a way for one application to send information in real time to another, notifying them about a specific event or new data.
Some key points about webhooks:
Instant Updates: Webhooks help different online tools stay updated with each other's activities in real-time.
Event-Based: They are triggered by specific events.
Messaging System: Think of them like text messages between apps. When an event happens, one app sends a message to another app with the details.
Information Exchange: These messages contain information about what happened, like the event type and time.
Automated: They're commonly used for automating tasks or connecting different apps together to work more smoothly.
For more information on the JSON schema used within the Brick, please follow the link below:
Deduplicate (Operator Brick): Checks for a key in the data. If the message is duplicated, it does not send the message again.
To configure this type of Brick, you needs to fill three things in the Brick's pane:
Key: What key to deduplicate for.
Period: For how long to take messages into consideration, for example, if you set the period for one year, it will only take into consideration messages from 1 year prior and no more than that.
Lookback: How many messages should the Brick take into consideration.
The syntax used for this type of Brick are:
Vector Remap Language (VRL), for more information on VRL syntax, follow the link below:
Jinja2, for more information on Jinja2 syntax, follow the link below:
If{{expression}} else (Operator Brick)
As the name suggests, it is a Brick used to decide what to do when given two choices.
For example: If the data meets specific criteria, proceed in this direction or take this action; otherwise, follow an alternative path or take a different action.
Use the branch at the bottom when the command matches if; otherwise, use the branch on the right when the command matches else.
For more information and syntax, please follow the link below:
Match (Operator Brick)
This Brick is used to verify if the data meets specific criteria. If it does, it can proceed through the flow.
For more information and syntax, please follow the link below:
Explode (Action Brick)
Takes a piece of data in a list and explodes the events. In other words, for every object inside the list, the Brick will create an event.
Gatekeeper (Operator Brick)
At times, you may have multiple flows or streams of information. The gatekeeper chooses which flow it will allow to proceed depending on the tasks time of arrival at the "gate".
Delay (Transform Brick)
Delays the flow for a specific period of time assigned by you.
In the delay panel, you can configure the desired delay duration using the Chat GPT prompt or a cron.
Merge (Action Brick)
This Brick merges the results of multiple tasks into one.
Within the Merge pane, you can configure the:
Max wait duration: Is the maximum amount of time to wait for incoming tasks to complete.
Merge type:
- Vector Remap Language
- Jinja2 Template
Implode (Transform Brick)
Collects multiple messages and emits an array. In simpler words, it does the complete opposite of the "Explode Brick," taking the events happening in each object of the list and combines them.
In the portal, when you select a Brick, you can find the Brick type listed next to the Brick's name.
Brick Manager
In this section of the portal, you can administer created Bricks and also create new ones.
To access the "Brick Manager," you should follow these steps:
- Navigate to "Settings."
- Click on the "Brick Management (v2)" section.
This action will reveal a tab where you can access the following details for each Brick:
- Title or name of the Brick
- Active version of the Brick
- Current version
- Type
- Date of creation
Additionally, you have the option to add a new Brick by clicking the "CREATE BRICK" button located at the top-right corner. This will open a tab asking you to provide a name, description, and parameters for the Brick.
Brick Management at the moment is internal, meaning it is not meant for users because it is still under development.
Recommended Approaches or Best Practices:
Multiple instances of a Brick
Encountering multiple instances of the same Brick can present difficulties within your workflow like overriding variables. Fortunately, a viable solution is provided by the Merge State Brick. This feature easily consolidates data from the initial occurrence of the Brick into a unified state variable, enhancing accessibility and streamlining operations.
Note that this issue can affect any Brick within your system.
Left output on a Brick
Be proactive with errors! Within the context of a Brick, the left output option serves as a valuable mechanism for error handling. When a Brick encounters an error, this functionality empowers you to take action. For example, consider the scenario where the "Create page-shot of" Brick encounters an error. In response, you can use this left output to initiate a five-minute delay before attempting to capture a page-shot once again. If the error continues, a predefined action, such as sending a notification via Slack will be triggered. On the contrary, if the Brick executes successfully, it proceeds with its intended operations.
Note that the availability of the "Left output" option may vary and is not universally applicable to every Brick.
| Last Update | December 11, 2023 |
|---|---|
| Important updates | 1. Added description about tasks search bar. |
| 2. Added Recommended Approaches or Best Practices section. |