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.

Last updated	July 29, 2024

---

What are Playbooks?

Playbooks allow you to create automated workflows by dragging and dropping Bricks 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 Bricks

Within Playbooks, the Raven Portal offers four types of Bricks:

1. 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.

2. 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.

3. 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.

4. Execute: Executes 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 Exectue Brick by the green color assigned to it.

   Execute Bricks have a left output in red color, this output provides an opportunity to add an action in case of an error.

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 the "NEW PLAYBOOK" button at the top right corner to start a new playbook. A window will open, prompting you to enter a name and description. Once provided, select the "CREATE" button, and a canvas will appear, allowing you to add and drop different bricks.

You can edit the name and description by selecting the EDIT DETAILS button in the top right corner.

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. Locate your bricks by clicking the orange icon on the left, marked with a "+" sign and a brick. Then, drag and drop them onto 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:

1. Disable: This button will stop the Brick from running, turning the Brick grey.

2. Enable: This button will start running the Brick, returning it to its original color depending on the category of the brick.

3. Duplicate: Gives you an exact replica of the selected Brick. No configuration needed, it will just duplicate the selected Brick.

4. Delete: This action will remove the selected Brick.

5. Save: This action will save the Playbook.

   Always remember to save the Playbook after any changes made.

---

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.