Playbook Assets

The Security Orchestration > Playbook Assets page allows you to create and manage Global Variables and Event Templates.

Global Variables

Global Variables are variables that can be used across multiple playbooks. Once declared, a global variable can be referenced in any playbook, eliminating the need to redefine it each time.

To create a global variable:

1. Navigate to Security Orchestration > Playbook Assets > Global Variables.
2. Click Create New.
3. In the Create Global Variable dialog, enter the following details:
   1. In the Variable Name, enter the name of the variable.
   2. In the Field Value field, enter the value for the variable.
   3. (Optional) In the Default Value field, enter a default value to be used if no value is provided by the user.
   4. Click Save to create the global variable.

Variable Names must start with a letter and can only contain letters and numbers. Special characters and spaces are not allowed.

To ensure the correct hostname appears in email links sent by System Playbooks, update the server_fqhn global variable. To update its value:

1. In the Global Variables list, click the Edit icon in the Actions column in the server_fqhn global variable row.
2. In the Field Value field, enter the appropriate hostname value. Optionally, add a default value,
3. Click Save.

If the hostname is not specified in the global variables, the default hostname used during FortiRecon installation will be included in the email. Ensure the server_fqhn global variable is used in the Send Email step of your playbook.

Event Templates

An event template defines events that trigger playbooks. By default, event templates are event-driven and use the provided Web Hook API to trigger playbooks when an event, to which the playbook is subscribed, is received. You can also modify event templates to fetch content periodically according to a set schedule.

In the FortiRecon UI, events are created using installed connectors, which typically include pre-built event templates. For example, the FortiSIEM connector provides an event template, "When an incident is created", which triggers playbooks when a FortiSIEM incident is created. You can further edit this template to configure periodic polling. You can also Creating Custom Event Templates.

Event templates also provide a simulation feature, allowing you to test the event template and associated playbook using sample data provided with the event template.

Web Hook API

Events can be posted by calling the following API endpoint:

METHOD: POST
URL: https://{HOSTNAME}/api/workflow/trigger/events
BODY:
{
"eventId":"fortinet-fortisiem.get_incidents_created",  	
"data": [
  {
    "eventType":{},
    "incidentID:{},
    "eventSeverityCat":HIGH			
  }
]  

Users can add a filter criteria as:

# Condition attribute from UI 
filters: 
  {
    eventSeverityCat:HIGH
  } 
}

The eventId must match the identifier defined in the event template. It is used to correlate with playbooks and filters.

Creating Custom Event Templates

To create a custom event template, follow these steps:

1. Navigate to Security Orchestration > Playbook Assets > Global Variables.
2. Click Create New Event Template.
3. In the Create Event Template dialog:
   1. In the Event Template Name field, enter a descriptive name that reflects the event triggering the playbook.
      For example, if the playbook should be triggered when a ticket is created, then the event template name can be added as "Get Created Tickets".
   2. The Event Identifier: Gets auto-populated based on the event template name.
      For example, if the event template name is added as "Get Created Tickets, the identifier will be set as "Get.Created.Tickets
      An event identifier provides the correlation with the playbooks and filters.
   3. (Optional) Click Add Event Description to provide additional details about the event.
4. (Optional) In the Configure Filter Criteria section, set conditions to trigger the playbook based on specific criteria. You can also define conditions when the event is used in a playbook.
   For example, triggering the playbook only when the event is of a specific type.
   To view sample events in JSON format click View Sample Events, which displays the Sample Events panel.
5. To ensure the event template is set up correctly and can process events, create a playbook that uses the template and click the Simulate button on the Sample Events panel.
6. Configure Periodic Event Polling:
   1. Toggle the Enable to configure periodic event polling option to fetch content from third-party integrations at defined intervals.
   2. In the Connector field, select the connector to use for triggering the playbook. For example, Fortinet FortiSIEM.
      Note: The connector must be installed for it to be listed in the Connector field.
      
   3. Configure the connector/connector parameters:
      • If using an included event template, such as from FortiSIEM, then the action based on which events would be fetched would already be selected and you need only configure the parameters as per your requirements.
        For example, for the List Incidents action of the Fortinet FortiSIEM connector, click the Edit icon in the Configure Connector Action: List Incidents section and configure the required parameters, such as, From Date, To Date, Incident Status, etc. These parameters will determine which incidents are fetched from Fortinet FortiSIEM.
        For custom templates, you must specify both the action, and the parameters used to fetch the events. In this case, click the Edit icon in the Configure Connector Action section, and from the Select action list. Based on the action selected, the input parameters will be populated. Configure these parameters to fetch content as per your requirements.
        
   4. Use the Schedule section to adjust the frequency of fetching content from the third-party integration.
7. (Optional) Use the Batch Processing (Looping) section to select your playbook execution preferences. Choose one of the following playbook execution options:
   1. Single Execution for Entire Dataset: Run the playbook once for the entire dataset.
   2. Execute in Batches: Recommended for large datasets to optimize performance. If selected, specify the Batch Size for processing.
8. Click Save to save the event template.

The Application Events trigger playbooks from either application events scheduled events. For details, see the Trigger Steps chapter.