Action Playbook Bricks
Explore this guide to discover the various types of Action Playbook Bricks, along with examples of popular ones used in the Playbook App. Learn how to set them up with easy-to-follow instructions, giving you a understanding of how they work and where they can be useful.
What are Action Playbook bricks?
Action Playbook Bricks are used to automate various tasks. These bricks can be created and managed within the Brick Management section.
Brick types
Trigger Bricks
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.
Examples of Trigger Bricks:
Forms
These Bricks are employed to manually trigger the Playbook. They operate 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
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
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
Webhook 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:
Execution Bricks:
Executions are tasks that are performed by the Playbook. They can be anything from sending an email to making an API call. Each Execution has specific inputs and outputs, and can be customized to suit the needs of the Playbook.
Examples of Execution Bricks:
Explode
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.
Merge
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
For more information on VRL and/or Jinja2 schema follow links below:
Webhook results
As the name hints this Brick collects the results of the Webhook. To configure this Brick you will need to fill in the "Template" which will indicate in a JSON language the structure of how the results are going to be shown.
For more information on the JSON schema used within the Brick, please follow the link below:
[Azure] User Update
Empower your workflow with the "Azure Update User" Brick, designed for seamless user updates in the Azure Active Directory. When integrated into your Playbook flow, a dedicated Pane unfolds, providing detailed insights and options for efficient user management.
Label: Within this section, you gain visibility and control over the Brick's name. Edit and customize it to align with your specific use case.
Credentials: In this segment of the Brick, you will need to provide valid credentials or a Secret. Generate a Secret by navigating to the settings and selecting the Secret section.
For more infomation about Secrets follow link below:
User Principal Name: Here, provide the User's principal name, ensuring accurate and targeted updates.
Template: This integral part of the Brick allows you to input information tailored to individual users, such as enabling or disabling specific features.
For more convenience, utilize the bottom of the Pane to verify and fine-tune the Brick's functionality. Insert desired events and variables to ensure optimal performance.
Windows Defender Actions:
Unlock the potential of device management with the "Windows Defender Actions" Brick, offering seamless control over pre-enrolled devices.
To learn more about managing devices follow link below:
To leverage this Brick effectively, provide the Managed Device ID, specifying the path to the device you intend to manage. Additionally, choose from a spectrum of actions to tailor the device's functionality:
Retire: Safely remove the device from active use.
Wipe: Perform a secure wipe, erasing data and restoring the device to its initial state.
Reset Password: Initiate a password reset for enhanced security.
Remote Lock: Securely lock the device remotely.
You can Test the node by selecting the "TEST" button located at the bottom of the pane, and inserting the events and variables.
Send to Topic:
Empower your workflows by broadcasting custom events to any pre-existing Topic within the Portal using the "Send to Topic" Brick. Follow these simple steps to enhance communication:
Select Target Topic: Specify the Topic to which the event will be sent. Choose from previously created Topics within Flows in the Raven Portal.
Craft Event Code: Within the template section, articulate the event by writing the code that encapsulates the desired information or functionality.
By seamlessly integrating this Brick, you amplify the connectivity of your system, ensuring timely communication and synchronization between different components.
Send Telegram Message:
Enhance your communication capabilities with the "Telegram Message Sender" Brick. This powerful tool allows you to send messages via Telegram by following these straightforward steps:
Specify Chat ID: Provide the unique chat ID to which the message will be sent. Ensure accurate communication by directing messages to the intended recipient.
Set Credentials: Add your Telegram credentials for authentication. Easily create these credentials by navigating to the Secrets section of the portal and selecting the Api KEY Secret type.
To learn more about about Secrets follow link below:
- Compose Your Message: Within the Template section of the Brick, create the message you wish to send. Utilize the flexibility of this Brick to convey information, notifications, or any other content seamlessly.
By incorporating the "Telegram Message Sender" Brick into your workflows, you ensure efficient and direct communication through the Telegram platform. Stay connected, informed, and responsive with this valuable addition to your toolkit.
Lookup IP Data:
Retrieve comprehensive information about an IP address with the "IP Data Lookup" Brick. Streamline your data analysis process by following these straightforward steps:
Provide IP Address: Simply input the IP address path for which you want to gather data. This intuitive step ensures that you target the specific IP address you intend to investigate.
Authenticate with Credentials: Enhance the security of your data lookup by supplying the necessary credentials. These credentials are crucial for accessing and retrieving accurate information associated with the provided IP address.
[raven] Run a query:
Elevate the functionality of your Playbook by seamlessly integrating the "Run a Query" Brick. This powerful feature allows you to perform queries directly within your Playbook, providing a streamlined approach to data retrieval and analysis. Follow these steps to configure the "Run a Query" Brick:
Credentials Configuration: Begin by adding the required credentials or OAuth 2.0 authentication. This step ensures secure access to the relevant data sources for your query execution.
Team ID Inclusion: Specify the Team ID to define the context for the query execution. Tailor your query to retrieve data specific to the designated team, enhancing precision and relevance.
Query Definition: Craft your query using Postgres SQL or PRQL languages. Define the parameters of your query to extract the precise data needed for your Playbook workflow.
Operator Bricks:
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 executions or transformations. On the other hand, if the data doesn't meet the criteria, the Operator Brick can reroute it or trigger different executions.
Example of Operator Bricks:
Gatekeeper
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".
Match
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:
If{{expression}} else
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 execution; otherwise, follow an alternative path or take a different execution.
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:
Creating an Action Playbook Brick
To create a new Playbook Brick:
Navigate to Settings / Brick Management V3.
Click CREATE BRICK in the top right corner.
Fill in the name and description, and select Action Playbook Brick as the type.
If you have an existing Brick you can use the fork option to skip various steps of the configuration process.
Configuration
Before using a Playbook Brick, several configurations are required. These configurations can be set in the Configuration > Configuration tab.
The configuration JSON includes the following fields:
| Name | Description | Type |
|---|---|---|
| brickId | A random identifier | String |
| label | The name of the brick as it will appear in Playbooks | String |
| description | The description of the brick | String |
| placeholder | Placeholder value for the brick | String |
| params | What parameters the brick can use. These parameters will be explained in the parameters section | List of objects |
| icon | The icon that will appear next to the brick in Playbooks. The icons section below will explain how to use icons | String |
| type | Can be one of execute, trigger, transform, operator. | String |
| input | Whether the brick allows input nodes | Boolean |
| output | Whether the brick allows output nodes | Boolean |
| canTest | Whether the brick gets a debug option | Boolean |
Parameters
Playbook Bricks can have multiple parameters to determine their behavior. The parameters can be of the following types:
text: Allows any string input.select: Provides a dropdown menu for selection.secret: Allows selection from configured secrets.jinja2: Indicates that the input string contains a Jinja template.prompt: Indicates that the input string contains an LLM prompt.
Each parameter has the following fields:
| Name | Description | Type | Required |
|---|---|---|---|
| name | Name of the parameter. Use this name to reference the parameter in your code. | String | Yes |
| label | The name that will be shown in the playbook | String | Yes |
| type | The parameter type. This can be one of the types shown above | String | Yes |
| placeholder | Placeholder value | String | No |
| default | Default value | String | No |
| required | Whether the parameter is required | Boolean | No, will default to False |
| options | A list of options for the select parameter type. These options have a value and a label | List of objects | Only required for select type |
| secretType | What type of secret to use (e.g. "BASIC", "APIKEY") | String | No, will default to all secret types |
Icons
The icon string should begin with:
data:image/{{image_type}}+xml;base64,
Where image_type can be png, jpeg, or svg.
This prefix should be followed by your base64 encoded icon.
Writing the Brick Code
To start coding your brick:
Navigate to Code.
Click + to add a Python file.
Name the file main.py.
Brick Class
Implement a Brick class that contains the core logic of your brick. This class should extend BaseBrick.
__init__()
This method initializes the brick and sets up its configuration.
Parameters:
config: A configuration object containing the parameters. You can retrieve the values using the parameter names as keys.
run()
This method contains the logic for executing the brick's task.
Parameters:
task(Object): An object containing task information with the following attributes:event(dict): The base event.state(dict): The playbook state.variables(dict): The output from upstream tasks.
in_nodes(list): Input nodes.out_nodes(list): Output nodes.
Returns: A routed_task (RoutedTask):
session_id(String): The task's session ID, retrievable from the input task (task.session_id).event(Dict): The base event, retrievable from the input task (task.event).
state(Dict): The playbook state, retrievable from the input task (state).variables(Dict): The variables, retrievable from the input task (variables).out_nodes(List): The output nodes.