Application Editor

Use the Application Editor to configure data models contained in modules, to export and import configurations, visually display the nodes related to a particular record, customize your Picklist values, and the left navigation bar.

The Application Editor has following tools for this purpose:

  • Module Editor - for editing the data models in a module
  • Picklist Editor - for changing picklist values and color associations
  • Navigation Editor - for modifying the navigation links and hierarchy in the left navigation bar
  • Correlation Settings - for configure the display of the visual correlation widget.
  • Configuration Manager - for exporting and importing configurations across environments

Important

To edit these settings, users must be assigned a role that has at a minimum of Read and Update permissions on the Application module. If you want a user to be able to add modules also, then those users must be assigned a role that has at a minimum of 'Read,' 'Create,' and 'Update' permissions on the Application module. To delete picklist or navigation items, you must have Delete permissions on the Application module. These privileges must be granted carefully as unintended application modification could result in data loss.

Module Editor

Use the Module Editor to add new modules and to add new fields and edit existing fields within a module. You can open the module editor by clicking Settings and in the Application Editor section, click Modules. This displays the Modules page.

Module Editor Interface

Important: Some fields in some modules are system fields and only FortiSOAR™ can create system fields. Changing the properties of the system fields could lead to issues with the working of FortiSOAR™. Therefore, you cannot modify any properties of these fields, and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module as shown in the following image:

Field Editor tab- Read-only fields

Modifying an existing module

To modify an existing module, do the following:

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.

  2. To edit an existing module, from the Select a module to edit or create new module drop-down list, select the module.
    For example, select Alerts.

  3. To add a module, you have to specify the properties on the Summary tab. You can also add or modify any field in the summary view for a module, by updating the properties or adding fields on the Summary tab. To add any field to the Summary view, you must ensure that you have already added the field using the Field Editor. This step describes editing properties in the Summary view.

    1. Edit properties on the summary view.
      You can configure the following fields for defining a module using the Module Editor:
      • Type: Type is similar to table name and is used to identify the module in the API. The Type name must be unique. The Type field must contain only lower-case alphabets, underscore characters _, and numbers, and it must start with a lower-case alphabet.
      • Table Name: The Table Name refers to the SQL table name generated. The table name must be unique and in lower-case. This generally matches the Type name. We recommend that you do not change the table name, or you risk data loss as the referenced table name changes, though the old table remains intact in the database.
      • Singular Name: The name of the module itself, when it is in the singular context (individual record). For example, an Incident refers to an individual record in a module, whereas the module is Incidents.
      • Plural Name: The name of the module itself when it is in the plural context. For example, Vulnerability is the singular version of the module and Vulnerabilities is the plural version of the module.
      • Display Template: This field uses an Angular Template expression to display a record appropriately. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ field_name_api }} .
        Important: Ensure that you add the fields that you specify in Display Template in the module that you are creating or updating. For example, if you have added {{ value }} in Display Template, then ensure that you have added Value as a field in the module, its Field Name (API) attribute will be set as value.
        Display Template
        You can also add an attribute of a picklist as part of the Display Template. See the following Display Template section for more details.
      • Ownable: Records that are ownable are owned by a Team or Teams. An example of a module that you should make ownable is Incidents. If you do not select this option, then the records are not ownable and are publicly available and visible to any system user, without consideration of the user's team. An example of a module that you could make not ownable is Addresses.
        Note: Records that do not have any owners are visible to "All." If you change a module that was not ownable to ownable, then the records created before you have changed the ownership are visible to "All". However, until owners (teams) are assigned to the record, the record is read-only, i.e., fields in that record cannot be edited until a team is assigned to the record. Also, users' who are editing the same record (with no owners) must assign their team to the records to ensure that the records continue to be visible to those users and/or teams.
      • Trackable: Selecting this option ensures that FortiSOAR™ tracks the date that the record was created, user who has created the record, date that the record was modified, and user who has modified the record on all records in the module.
        Important: Once a module has been created, you must not modify the Type and Table Name fields. You can edit the Singular and Plural names whenever required. However, note that the Singular name plus an s is used for API endpoint generation during module creation. Changing the Singular name could disrupt existing API calls to the endpoint.
      • Taggable: Selecting this option ensures that the selected module is taggable, i.e., you can enter tags to records in this module making it easier to search and filter records in the module.
      • Data Replication: (Introduced in FortiSOAR™ 6.0.0 for MSSP setups): Selecting this option enables replication of data for the selected module across peers setups.
      • Record Uniqueness: This section allows you to choose one or more published fields from the existing module that would be used to define a unique condition. This ensures that only unique records will be created in FortiSOAR™ and any record that matches the unique field or the combination of unique fields would not be created.
        For example, Type + Value is a unique combination in the Indicators module as shown in the following image:
        Application Editor: Summary Page - Record Uniqueness section
        This will ensure that indicator records will be created with unique "Type and Values" values.
        If you want to add any other field to for part of the unique combination of fields, then from the Record Uniqueness section, select that field from the Select a Field drop-down list, and then click Add Field. Similarly, if you want to remove any field from the unique combination, you need to click the red X on that field.
      • Default Sort: Click Add Field to add a field based on which the list of records in the module will be sorted, either in the ascending or descending order. For example, indicators will be sorted based on when they were created, if you add Created On in the Default Sort section, as shown in the following image:
        Module Editor - Existing Incident module
    2. Click Save to save the changes to the module or click Revert to clear any changes made in the interface since the last Save event. For information on the save and revert operations, see the Saving your changes section.
  4. To add fields to the module, or to edit any of the fields belonging to the module, add or update the fields on the Fields Editor tab on the Modules page.
    Editing Field Properties
    Important: Some fields in some modules are system fields and changing properties of these fields could lead to issues with the working of FortiSOAR™. Therefore, you cannot modify any properties of these fields and they appear as read-only when you select them in the Fields Editor tab. An example of this type of field is the First Name field in the People Module.

    1. To add fields, on the Modules page, click the Fields Editor tab and click the Add (+) icon beside Fields.
      Note: The Fields Editor pane displays the list of fields that have been defined for the module. You can filter the fields by typing the search term in the Filter Fields textbox:
      Filtering Fields in the Fields Editor
    2. Define the following properties for the newly added field:

      • Field Type: The type of field; it specifies the type of form used to render this attribute. Examples of field types are text, checkbox, integer, decimal, date/time, picklist, and relationship fields.
        It is recommended that when you create a field of type Integer, then you should set its default value as "zero".
        FortiSOAR™ 6.0.0 introduces the JSON field type, which can be used for fields such as Source Data that commonly store data in the JSON format. Using JSON as a field type for such fields allows playbooks to get to the JSON data directly, without having to use a JSON parse step. You can also define the height of the JSON field in pixels by editing your record template.
        Based on the Field Type that you select, you can see an additional field. For example, if you select the field type as Picklist, a Picklist drop-down list will appear, and you must select the picklist associated with the field or click Create new picklist to add a new picklist. FortiSOAR™ 6.0.0 introduces a Configure Picklist Option Visibility checkbox using which can filter a picklist field based on specified criteria. Once you check this checkbox, the picklist items are displayed and you can choose whether the item should be Visible, Disabled, Hidden, Conditionally Visible, or Conditionally Enabled. If you choose Conditionally Visible or Conditionally Enabled, you can then define the criterion when this item should be visible. An example would be displaying the Minimal option, in case of the Severity picklist, only if the type of alert is Other / Unknown:
        Configure Picklist Option Visibility
        FortiSOAR™ also supports a special type of picklist, called "Multiselect Picklist". You can use the multiselect picklist for fields that can contain more than one value. For example, you can have an alert be assigned more than one "Type", i.e., an alert can be of type Brute Force Alert and Malware. In such a case you can assign Multiselect Picklist as the Field Type for the "Type" field. You can then select an existing picklist from the picklist drop-down list, for example AlertType, or click Create new picklist to create a new picklist. You can also click Modify picklist to modify the existing picklist, by adding or removing picklist items or changing the properties of the picklist items.
        Field Type - Multiselect Picklist
        If you select Lookup (One to Many or One to One), Multiple Relationship (Many to One), or Multiple Relationship (Many to Many), a Related Model drop-down list will appear, and you must select the related module. The related module is the module for the source of the data, which is not explicitly defined, to which the fields points.
        Notes with respect to Relationship fields:
        -- In the case of a Multiple Relationship (Many to One), or a Multiple Relationship (Many to Many) field, you must select the appropriate field from the Related Model drop-down list, before you publish the module.
        -- In the case of Lookup (One to Many or One to One) fields that have People as a related module contain the Filter Setting section. If you select the Only show users with record ownership checkbox in the Filter Settings section, then the list of users displayed in the lookup on the UI is restricted to include only those users who have record ownership. Further, you can also limit the list of users displayed in the lookup based on permissions given to the user on the module using the Limit ownership users to ones with module access to option. In the Limit ownership users to ones with module access to option, you can choose to display users who have Read access or Update (Read + Update) access.
        Filter Settings section
        Example: In the Alerts module, we have an Assigned To field, which is of type Lookup (One to Many or One to One) , with People as the related module. In this case by default, all users will be displayed in the Assigned To lookup, when you open an alert record. However, this could include users who belong to other teams, and who, therefore, would not have access to the record, even if you assign that record to that user.
        Therefore, to restrict the users to only those users who have access to the record, you can select the Only show users with record ownership checkbox. You can further restrict users displayed in the Assigned To lookup based on the module access. For example, if you want to display only those users who can update the record, in the Limit ownership users to ones with module access to field, select the Update checkbox (once you select the Update checkbox, the Read checkbox is automatically checked).

      • Sub-Type: The "Sub-Type" field can be used along with the Text field type. When you select Text in the Field Type, then an additional field named Sub-Type is displayed. You can select the sub-type such as, Text Field, Rich Text, Text Area, IPv4, IPv6, Domain, URL, or Filehash. The sub-type field enforces the format of data that the user can enter in that field. For example, in a Rich Text field, you can can use formatting options or you can use the IP address and domain field types to lookup threat intelligence tools and whois info.

      • Field Name (API): The name of the field. This is a required field. The Name field must be alphanumeric and must start with a lower-case alphabet. It cannot contain any spaces, underscores or any special characters.
        Note: You cannot change the name that you specify for the field once the field has been created and the module has been published. This is because there is no migration path from the old name to the new name, so you risk data loss if you change the field name.
      • Field Title: A short descriptive name describing the item.
        Note: If you have a field, in a module, whose Field Title (Singular Description) attribute value contains a . or $, then the Audit Logs replace the . or $ with an _. For example, if you have a field SourceID whose singular description you have specified as Source.ID, then in this field will appear as Source_ID in Audit Logs.
      • Editable: Selecting this option allows you to modify the field after the creation of a module record. If this option is not selected, then you cannot modify the initial value after the record is created.
      • Searchable: Selecting this option makes this field searchable in the grid view.
      • Default Grid Column: Selecting this option makes the field appear as a column by default in the grid view. The order of the grid columns is defined by order of the fields in the Field Editor list. For information about grids, see the Dashboards, Templates, and Widgets section in the "User Guide."
      • Encrypted: Selecting this option enables encrypting of field values before storing in the database for enhanced security. FortiSOAR™ UI will continue to display the non-encrypted values. Currently, Text Fields, Email Fields, Rich Text Area and Text Area fields can be encrypted.
        Important: Once you enable encryption you cannot search the field values using FortiSOAR™ UI. Filters also will not work on encrypted fields. You also cannot use the upsert functionality for fields that are encrypted.
      • Required: Specifies whether the field is a required field.
        The options are: Not required, Required, or Required (by condition).
        Once you select Required (by condition), FortiSOAR™ displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR™ 6.0.0 adds support for advanced date operations and nested conditions for the Required (by condition) fields i.e., the Add Condition Group link is now available for these fields.
        Important: Do not choose the Visibility = Hidden option for Required (by condition) fields.
      • Visibility: Specifies whether the field is visible or not.
        The options are: Hidden, Visible and Visible (by condition).
        If you select the Hidden option, then the field is only accessible at the API level and not shown in the UI.
        If you select the Visible option, then the field is displayed on the UI. If you select the Visible (by condition) option, then the field is displayed on the UI only if the specific conditions are met.
        Once you select Visible (by condition), FortiSOAR™ displays the Condition Builder options where you must add the necessary condition.
        Note: FortiSOAR™ 6.0.0 adds support for advanced date operations nested conditions for the Visible (by condition) fields i.e., the Add Condition Group link is now available for these fields:
        Visible By Condition - Nested Conditions
      • Default Value: Specifies the default value of this field. Once you specify a value in this field, then this value will be displayed, by default when you add a record in the selected module.
        For example, if you want the status of a newly created alert to be set to Open, by default, then select the Status field and from the Default Value drop-down list, select Open as shown in the following image:
        Default Value option
        Once you set the default value, then whenever you add a new record in the Alerts module (in our example), then by default Open will be displayed in the Status field.
        In the Default Value field for the Date/Time field type you can specify either a Static date/time or a Custom date/time. If you select Static, click the Select Date icon to display the Calendar and select the required date/time. If you select Custom, then you can specify a date/time relative to the current date/time such as 1 hour from now, or 3 hours ago.
        Enhanced Default Value field for Date/Time field
        Note: In case you have upgraded to version 5.0.0 or later, then you will have to reselect your datetime default values, since the new datetime format is not backward compatible. You will be able to see the older applied datetime default value in the FortiSOAR™ fields. However, if you want to edit the default field, then you will have to specify the datetime again in the Default Value field.
      • Tooltip: Brief definitions that you can optionally add to fields. This definition is displayed when you click the information (i) icon of the field that has tooltip information added while creating, updating, or viewing records.
      • Length Constraints: In case of a Text field with sub-type set as Text Field, you can specify length constraints by clicking the Add minimum/maximum range checkbox, if you want to override the default field length constraints by providing a minimum-maximum range for a field. Once you select the Add minimum/maximum range checkbox, you can specify the minimum character length for the field in the Minimum field and the maximum character length for the field in the Maximum field. You can enter any number from 0 to the maximum character length that is applicable for that field in the database. FortiSOAR™ will display a validation message if the maximum character length for the field is exceeded, or if the minimum character length for the field is not met.
      • Bulk Edit: Selecting the Allow Bulk Edit option to allow bulk edit operations on the selected field.
        For example, if you have selected the Severity field, in the Alerts module, and have clicked Allow Bulk Edit, this means the users can select multiple records in the grid view of the Alerts module and change the severity of those records to a particular severity level.
        You must enter the following details for the button that you want to use for the bulk edit operation:
        Button Text: In the Button Text field, type the name of the label that will be displayed on the bulk action button. For example, type Change Type.
        Button Icon: From the Button Icon drop-down list, select the icon that will be displayed on the bulk action button. If you do not want an icon to be displayed, select None.
        Button Classes: From the Button Classes drop-down list, select from the Default, Primary, Danger, or Warning styles.
        Allow Bulk Edit option
        Once you save the changes and publish the module, a Change Severity button is added to the Alerts module in the action bar. For more information on how to use the bulk action button, see Working with Modules - Alerts & Incidents. You can add the bulk edit action button for any other fields, such as Status, Assigned To, and Type.
        1. Click Apply to add the field or click Revert to clear any changes made to the field since the last Save event or click Remove to remove the field.
          For information on the save and revert operations, see the Saving your changes section.
  5. You can also define the order of the default grid columns, which is defined by the order of the fields in the Fields Editor list. Fields are listed in the Fields column and you can drag-and-drop the fields to sequence the fields. You can also filter fields using the Filter Fields box.
    Defining the sequence of fields

  6. Click Save to save the changes to the module or click Revert > Revert to last saved to clear any changes made in the interface since the last Save event or click Revert > Revert to last published to clear any changes made since the last Publish event. For fields, you can revert only to the last published instance.
    For information on the save and revert operations, see the Saving your changes section.

Once you have completed making modifications to the module, you must publish the modules to reflect the changes in the system. This takes the system down for up to a few minutes while the changes are made. See the Publishing Modules section for more information.

Note

The Module Editor changes the relational database schema, therefore for changes to go live in the environment, you must perform a Publish to the database. This temporarily takes the application offline while the database operations are being performed. All users in the application must save their work prior to this occurring before this occurs or you risk data loss.

Display Template

A module's Display Template refers to one or more fields in the data model itself that is used to display a record in the general interface. Certain widgets, or visualizations in the interface, use the Display Template to identify records to the user. This template specifies the fields that will be displayed when a record from this module is referenced in the application. Fields of a module can be specified in the display template as {{ <*name of the module's field*>_name}}. If multiple fields are part of the display template, then you can specify multiple fields as {{field_name1,field_name2,}}.

FYI

If you were to use just the name of the module itself, such as Incidents, every Incident record in the interface would include a label named Incident. So, users see the Incident label with every record, which is not helpful. Therefore, we use Templates with a language to describe how to label your modules.

You can also include an attribute, such as itemValue, of a picklist field in the Display Template, add the following jinja: {{picklistFieldName.itemValue}} . For example if you want to include the status of the alert in the Display Template, then the picklist to be used would be AlertStatus, and the picklist field name would be status:

Example of adding jinja in Display template for picklists

Therefore you require to add the following jinja: {{status.itemValue}} in the Display Template.

Example

We have taken the Asset module as an example. Assets represent computing resources, typically on the network. Assets generally have a hostname, IP Address, or MAC Address. We are using the hostname as an example.

To create a Display Template for the Assets module with the hostname, you must ensure that you have already added the hostname field using the Field Editor. Once the hostname is added as a field in the Assets module, use the following expression in the Display Template field:

{{ hostname }}

The double curly braces, {{ }}, is used to identify a variable, specifically a field name. In our case, we are calling the hostname field. Any expression in the Display Template field that uses a field from the module data fields must use the double curly braces surrounding the field name. When the record is displayed, the hostname of each asset is used in the interface, so users know the asset they are selecting. For example, a user can know that they are selecting an HR Server.

Assets have a unique situation. They might only have one of those pieces of identifiable information depending on what is known about a resource. A laptop on a DHCP network might have only a MAC address. If we set the Asset Display Template to always be a hostname, in many cases the asset might have a blank Display Template in the interface. For these situations, the Angular Template expression allows you the flexibility to modify the format of the Display Template in a way that can account for variation. Taking the asset example, asset information is used to help users identify the asset when in the interface. Because using only a single asset field could potentially lead to a lot of blank Display Templates, we use multiple fields such as hostname, IP address and Mac address:

{{ hostname }} {{ ip }} {{ mac }}

This Display Template expression instructs the system to use all three fields based on their field names. If a field is not present, it displays as blank. In some cases, depending on what is known about the asset, the Display Template will include all three pieces of information, in others just one.

You can further extend this to display static information that identifies the parts of the Display Template. The following example includes the static text of Hostname: IP: and MAC: in every Display Template. This might be redundant but is an option.

Hostname:{{ hostname }} IP:{{ ip }} MAC:{{ mac }}

We recommend that to keep things simple, most of the time you would want to use the following expression for a Display Template, assuming you always create a name field for a module:

{{ name }}

This ensures that the Display Template points to whatever is in the name field on any module record. If you create name as a required field, then it will always be populated.

  1. Click Settings and click Modules in the Application Editor section, to open the Module Editor.
    This displays the Modules page.
  2. On the Modules page, from the Select a module to edit or create new module drop-down list, select the first module that you want to relate.
    For example, select Alerts.
  3. Click the Fields Editor tab and click the Add (+) icon beside Fields.
  4. Set the following values:
    Field Type: Multiple Relationship (Many to Many)
    Related Module: Module that you want to relate. For example, Indicators
    Related Field (Optional): blank (for now)
    Field Name (API): Exact name of the related model. For example, indicators
    Field Title: Name to describe the related model. For example, Indicators
    Editable: Select editable to allow the field to be modified after creation of a module record. If this is option is not selected, then the initial value of the field cannot be changed after the record is created.
    Application Editor: Relating alerts to indicators
  5. Click Save.
  6. On the Modules page, from the Select a module to edit or create new module drop-down list, select the other module to be related.
    For example, select Indicators.
  7. Click the Fields Editor tab and click the Add (+) icon beside Fields.
  8. Set the following values:
    Field Type: Multiple Relationship (Many to Many)
    Related Module: First module that was related. For example, Alerts
    Related Field (Optional): blank (for now) Field Name (API): Exact name of the first related module. For example, alerts
    Field Title: Name to describe the related model. For example, Alerts
    Editable: Select editable to allow the field to be modified after creation of a module record. If this is option is not selected, then the initial value of the field cannot be changed after the record is created.
    Application Editor: Relating indicators to alertss
  9. Click Apply.
  10. Select the same name and set the value Related Field (Optional) field to the related field in the other module. For example, indicators.
    Applying the related field in the Indicators module
  11. Click Save.
  12. Select the first module, in our case Alerts, and then click the Fields Editor tab, and select the field that you had created.
  13. Set the value Related Field (Optional) field to the related field in the other module. For example, alerts.
    Applying the related field in the Alerts module
  14. Click Save.
  15. Click Publish All Modules and wait for the publishing to complete.
    Now, the modules must show the relationship, i.e., both the Indicators and Alerts modules will have a tab to relate to each other.

Note: You must perform a similar procedure to relate two modules using the Lookup (One to Many or One to One) field type. If you add the related field to only one of the modules, you can get an error, while publishing, as follows: Inversed field 'alert' does not exist on related model metadata. Module 'UUID of Module 1' Field 'UUID of Module 2' on 'inversedField'.

Creating a New Module

To create a new module, click Settings > Modules. This displays the Modules page. Use the +Create new module option that appears at the top of the editor to define the properties of the module. By default, when choosing the Module Editor, the ability to define the new modules is available.

Adding a new Module

Bear in mind there are requirements to realize the addition of the new module, notwithstanding the need to allow for the interface to recognize this module.

See the Modifying an existing module section for information on how to add and edit fields. After you have completed adding fields to the module, click Save to save the changes to the module and publish the module to reflect the changes in the system. For information on the Save operation, see the Saving your changes section. For information on publishing, see the Publishing Modules section.

Saving your changes

Whenever you make any changes to a module or a field, you must stage those changes by saving. At the top-right of the Module Editor is the Save button, which applies any changes made to the staged data. To update the database and make your changes to go live, you must Publish the updated modules.

The Revert button clears any changes made in the interface since the last Save event. If you go into a module and realize that you have edited the wrong field, use Revert to clear the changes. However, once you press Save, you require to undo the changes manually.

Viewing your changes

Editing any of the fields of a module does not mean those fields are accessible immediately within the UI or the API. The fields must be first represented in the database. The templates included might automatically discover these fields, or these fields might need to be added manually to the template to specify their location within the interface. However, you can set the grid defaults within the attribute data for the model itself.

To update the database and make your changes to go live, you must Publish the updated modules.

Publishing modules

Whenever you change a field or a module and click Save, the change is staged but is not yet live in the system. You must perform a Publish to ensure that the changes are made in the system.

You initiate a publish action by clicking the Publish All Modules button at the top-right of the Module Editor page. Publishing pushes the changes that you have made to fields and modules to the database. Up until the Publish point, all changes to the data model in the Module Editor are saved as metadata, which is information that describes the structure of other information.

A Publish is the point at which the changes are truly irreversible, meaning that an unintended field deletion could cause irretrievable data loss. Use Publish carefully and verify changes before Publishing to avoid any problems.

Publishing is a sensitive operation

We recommend that you send a prior notification to all users of a publish since while the publish is in progress users are unable to work. We also recommend reviewing each staged change to ensure that only the desired changes are going to take effect.

If there is any error during the publish operation, FortiSOAR™ displays a meaningful error message at the top of the module editor, so that it becomes easier for you to resolve issues.

Note

If you have not selected an appropriate field from the Related Model drop-down list, for a Multiple Relationship (Many to One), or a Multiple Relationship (Many to Many) field, then the publish operation will display an error.

Picklist Editor

Use the Picklist Editor to change the values of any picklist within the modules and add new picklists that might be referenced by a field in any module.

Unlike the Module Editor, changes made in the Picklist Editor are immediately live once they are saved. This is because Picklists names and Picklist values are records in the database.

A UUID (Universally Unique Identifier) identifies picklist values, which means if you modify any of the names or colors of an existing picklist value, the original data is preserved. Therefore, all records that contain that picklist value retains a reference to the UUID for the picklist. This means that if you want to change an Incident Category of Theft to Physically Stolen, you could make that change on the existing Theft value and any records with the value of Theft would now display Physically Stolen.

Picklist Editor

Creating or modifying a picklist

To add or modify a picklist:

  1. Click Settings and in the Application Editor section, click Picklists.
    This displays the Picklist Editor.
  2. Add or edit an existing picklist. To add a picklist, use the +Create new picklist option that appears at the top of the editor to define the properties of the picklist. Start by entering a title for the new picklist in the Title field.
    Or To edit an existing picklist, from the Select a picklist to edit or create new picklist drop-down list, select the picklist.
    For example, select AlertStatus.
  3. In the Items section, in the + Type and Press ENTER To Add New Picklist Item field, enter the name of the new picklist item and press Enter.
    For example, for the AlertStatus picklist, add items such as Open, False Positive, and Verified.
    Or
    To edit a picklist item, click the Edit icon that appears on the item row, update the name of the item or the color assigned to the picklist, and then click the green tick mark icon.
    Editing Picklist items
  4. (Optional) You can add colors to any picklist, by checking the Assign Colors checkbox. Once the Assign colors checkbox is enabled, you can assign each item in the picklist a color.
    Use the color picker box that appears next to each item in the picklist or enter the hexadecimal code for the color to edit the colors. You can use any valid HTML color.
    You can set the picklist color by directly entering the hexadecimal code of the color and assigning that as the picklist color, or by using an API, or you could choose colors by clicking in the color picker.
    The following image shows how to enter a hexadecimal code (#ff0000 for red color) in a picklist:
    Entering picklist colors using hexadecimal values
    Note: Multiple items in a picklist can have the same color.
  5. (Optional) You can also remove all items from the picklist by clicking the Removing All Items button, and you can also change the sort order of the picklist items clicking the Ascending or Descending order icon (Ascending or Descending Order icon).
    Picklist completed
  6. Click Save to save the changes made to the picklist or click Revert to clear any changes made to the picklist since the last Save event or click Remove Picklist to remove the picklist.
    You can also click the Audit Log button to view logs specific to a particular picklist. For more information on Audit Logs, see the System Configuration chapter.

Pages are iFramed resources that are accessible from the application interface by the user, such as resource pages and wikis within the local environment or on an accessible website link. Pages must currently be added in the modules API to be present to add in the Editor.

Use the Navigation Editor to modify the system Navigation bar, present on the left-side of the application interface.

Note

Changes that you make to the to the left navigation bar using the Navigation Editor affects all users. Currently, these changes cannot be made at a user-specific level.

Navigation Editor

There are two types of Navigation values:

  • Single-level navigation item, in which case an icon and title on the Navigation bar represent a module or page
  • Two-level navigation item, in which case an icon and title reveal a menu of additional options. Secondary navigation items might only have a name, not an icon.

You can add an external HTML page in an iFrame and display that page as part of the left-navigation in FortiSOAR™.

Modifying the Navigation bar

To modify the Navigation bar:

  1. Click Settings and in the Application Editor section, click Navigation. This displays the Navigation Editor.
  2. Add or modify the navigation bar:
    To add a single-level item, select module or pages by clicking the Modules or Pages tab, and click Add To Menu. Single level items on the menu must represent a 1:1 relationship with a module or page.
    To add a two-level item, select modules or pages by clicking the Modules or Pages button, and click Add As Group.
    The second-level navigation item is not a hyperlink or capable of referencing a given module or page. Only the sub-items in the group can be linked as a module or page. Clicking any two-level Navigation group shows and hides the sub-items.
    For example, you want to create a menu-group named Artifacts Management that has Attachments, Comment, and Scans as the menu items. You select the Attachments, Comment, and Scans modules and click Add As Group.
    This creates a menu group as shown in the following image:
    Example of a two-level menu group
  3. Edit the menu items by clicking the Edit icon that appears on the item row, update the name of the menu item or replace the icon of the first-level item in menu group, and click the green tick mark icon.
    You can replace icons by choosing icons from the icon selector at the left of each Navigation item.
    You can also delete a menu item by clicking the Delete icon.
    Example of editing a two-level menu group
  4. Drag-and-drop modules or module groups to change the order of the navigation items in the Navigation bar.
    Note: The top item of the navigation is always the default login page. By default, this is the dashboard page. However, you can modify this to make any other page the home page.
  5. (Optional) To add an external HTML page in an iFrame and display that page as part of the left-navigation in FortiSOAR™, click the Pages tab and click the Add More link.
    Navigation Editor: Pages Tab - Add More link
    1. In the Title field, enter the name for the HTML page that you would want to display in the left navigation menu.
      For example, if you want to add a link to the Google website as part of your left-navigation in FortiSOAR™, enter Google in the title field.
    2. In the URL field, enter the URL for the HTML page that you want to display in an iFrame. For our example, enter https://www.google.com.
    3. Click Add Page.
      Adding Title and URL of the HTML page that you want to display in an iFrame
    4. On the Pages tab, select the page you have just added, Google in our example, and then click Add To Menu or Add As Group according to your requirements.
      Adding the HTML page to the Navigation Menu
  6. Click Save to save the changes made to the menu items or click Revert to clear any changes made to the menu items since the last Save event.

Correlation Settings

If you want to use the Visual Correlation widget to visually display the nodes related to a particular record, then you have to configure the display of the various related nodes on the Visual Correlation Setting page.

The following procedure is an example where you are configuring the display of alert nodes that has associated indicator nodes:

  1. Click Settings and in the Application Editor section, click Correlation Settings.
  2. On the Visual Correlation Setting page, from the Choose Modules To Define Correlation View Configurations drop-down list, select the module for which you want to define visual correlations and then click Add and Configure.
    Note: FortiSOAR™ has pre-configured five modules, Alerts, Incidents, Indicators, Vulnerabilities, and Assets. The default depth of the nodes displayed is 3, i.e, if you start from the Alerts node, you view its related Indicators and if those indicators have related assets, you can view those related assets.
    For our example, we require the Alerts module, so we do not require to perform this step.
  3. On the Alerts bar, click the down arrow and then configure the following parameters:
    1. From the Choose Related Modules drop-down list, select the module that should be shown in the correlation graph as linked modules and then click Add Related Modules.
      Note: There are some modules that are pre-configured as related modules for the Alert module such as, Alerts, Incidents, Indicators, Vulnerabilities, and Assets.
      For our example, we require to add Indicators as a related module to the Alerts module, so we do not require to perform this step.
    2. From the Node Label drop-down list, select the field that will be shown as a label for the node.
      By default, this is set as Name.
      For our example, choose ID.
    3. From the Node Color drop-down list, select the field that will conditionally determine the color of the node.
      By default, this is set as Severity, which is what we need for our example. You can also choose Status, Type, or Escalated.
      Note: In case of a picklists the color of the node is determined by the color that you have assigned to the value of the picklist item. For example, if you have chosen the Severity as the picklist, then the colors that you have assigned to the selected picklist value will be used as the node color. For example, if the Severity is set as Critical, then the node color will appear as Red, if its High, then the node color will appear as Orange, if its Medium, then the node color will appear as Yellow, etc. Therefore, if the alert in which you have added the visual correlation widget is Critical, then its node color will be Red.
      You can also determine a custom color for the node by using the Choose custom color picker.
      If you do not specify any color, the node will appear as black.
    4. From the Node Shape drop-down list, select a shape that will be shown as the shape of the node.
      For our example, choose Square.
      Configured correlation settings for the Alerts module
      You can also choose to specify a custom icon as the shape of the node. In this case choose Custom Icon from the Node Shape drop-down list and click Change to add the custom icon.
      Node Shape - Custom icon
      Clicking Change displays the Upload an Image dialog, and then drag-and-drop the icon file, or click the Import icon and browse to the icon file XML file to import the icon file into FortiSOAR™ and then click Save Image.
      Note: The custom icon should be 15px X 15px and the file size must be less than 10KB. Also, once you select a custom icon, you cannot specify the node color.
  4. Next, you require to define how the related record node will also be displayed. For our example, we have to configure the Indicator module, which is a pre-configured module, so we do not require to add this module.
  5. On the Indicators bar, click the down arrow and then check the pre-configured parameters and change them as per your requirements:
    1. From the Choose Related Modules drop-down list, select the module that should be shown in the correlation graph as linked modules and then click Add Related Modules.
      Note: The Alerts module is already added as a related module to the Indicators module.
    2. From the Node Label drop-down list, select the field that will be shown as a label for the node.
      By default, this is set as Value.
    3. From the Node Color drop-down list, select the field that will conditionally determine the color of the node.
      By default, this is set as Reputation.
      From the Node Shape drop-down list, select a shape that will be shown as the shape of the node.
      By default, this is set as Circle.
  6. Click Save to save the settings for visual correlation.

Now if you have added the Visual Correlation Widget in the Alerts detail view (see Dashboards, Templates, and Widgets chapter in the "User Guide"), it will display as shown in the following image:

Display of the configured Visual Correction Widget in the Alerts Details view

As you can see in the above image, the Correlations graph has a title which is Indicators associated with the Alert. The title can be specified by the user when they are adding the Visual Correlation Widget. The alert for which the associated indicators are displayed is shown as a square node, whose color is determined by its severity, Orange in this case since the alert has severity set as High. The ID of the alert displayed as the label of the node. The associated indicators are displayed as circular nodes, whose colors are determined by their reputation, hence one circles are red (reputation set as malicious), one is yellow (reputation set as suspicious), one is light green (reputation not available), and one as grey (reputation TBD). The value of the indicator displayed as the label of the node.

Configuration Manager

Use the Configuration Manager to export configuration or metadata information of your models, view templates, and picklists from FortiSOAR™. You can also import configurations or metadata information for modules from other environments into FortiSOAR™ using Configuration Manager. Configuration Manager, therefore, enables you to move model metadata, picklists, and system view templates across environments.

Important

Do not import MMDs between major releases of FortiSOAR™. For example, do not import an MMD from version 5.x into version 6.x.

Using the Configuration Manager, you can export and import dashboards, reports, system views, roles, and picklists not related to modules. The system views that you can export, and import are for Queue Management Configuration and Navigation.

Using the Configuration Manager, you can replace picklist items during import instead of skipping them. You can also select the Keep Existing Fields By Default check box to retain fields that were present in an existing module, but which are not present in the exported (new) module. For example, if you have an Alerts module existing on your FortiSOAR™ Env1 having a field named Notes and you have exported the Alerts module from FortiSOAR™ Env2, which does not have the field named Notes. Now, when you import the Alerts module configuration from FortiSOAR™ Env2 to FortiSOAR™ Env1, the Notes field is retained in FortiSOAR™ Env1 if you have checked the Keep Existing Fields By Default check box.

Note

FortiSOAR™ ensures that you either revert or publish staged changes prior to importing configurations so that there are no issues during the import process.

Exporting configurations

To export configuration or metadata information of your models, view templates, and picklists from FortiSOAR™:

Exporting Modules:

  1. Click Settings and in the Application Editor section, click Configuration Manager. This displays the Configuration Manager page.
  2. On the Export Configuration tab, on the Modules tab, you can select the module (s) that you want to export.
  3. In the Export Options section, select the configurations that you want to export.
    Click the Include Model Metadata option to export configuration information of the modules that you have selected.
    Once you click the Include Model Metadata option, the Include Picklists option is automatically selected, since the picklists associated with the module must also be exported when you are exporting the configuration information for the modules to ensure there are no issues when you import the configuration to another environment.
    Click the Include View Templates option to export configuration information of the templates that you have created for the selected module(s).
    Click the Include Picklists option to export configuration information of the picklists that you have created for the selected module(s).
    Note: Once you select a specific module then the picklists associated with that particular module are automatically selected For example, if you select the Alerts module, the AlertStatus, AlertType, and EscalatedToIncident picklists are automatically selected.
    By default, all the export options are selected.
  4. Click the Export Configurations button to export the specified configuration information of the modules that you have selected.
    FortiSOAR™ exports the specified configuration information in the JSON format. FortiSOAR™ displays warnings if there are any inconsistencies in the data, such as templates not found, to be exported.
    Configuration Manager - Exporting modules
    You can now use the JSON file containing the exported configurations in another environment.

Exporting Dashboards and Reports:

  1. Click Settings and in the Application Editor section, click Configuration Manager. This displays the Configuration Manager page.
  2. On the Export Configuration tab, click the Dashboards tab or the Reports tab and select the dashboards or reports that you want to export.
    Click All to select all the dashboards or click Uncheck All to deselect all the dashboards.
  3. Click the Export Configurations button to export the specified configuration information that you have selected in the JSON format.

Exporting Picklists:

  1. Click Settings and in the Application Editor section, click Configuration Manager. This displays the Configuration Manager page.
  2. On the Export Configuration tab, click the Picklist tab and select the picklist (s) that you want to export.
    Click All to select all the reports or click Uncheck All to deselect all the reports.
    Using this tab, you can export those picklists that are not associated with any module.
  3. Click the Export Configurations button to export the specified configuration information that you have selected in the JSON format.

Exporting System Views:

  1. Click Settings and in the Application Editor section, click Configuration Manager. This displays the Configuration Manager page.
  2. On the Export Configuration tab, on the System Views tab, you can select the system views that you want to export.
    You can export the Queue Management Configuration and Navigation system views.
    Click All to select all the system views or click Uncheck All to deselect all the system views.
  3. Click the Export Configurations button to export the specified configuration information that you have selected in the JSON format.

Exporting Roles:

  1. Click Settings and in the Application Editor section, click Configuration Manager. This displays the Configuration Manager page.
  2. On the Export Configuration tab, on the Roles tab, you can select the role(s) that you want to export.
    You can export roles such as Full App Permissions, Application Administrator, T1 Analyst, Security Administrator, etc.
    Click All to select all the roles or click Uncheck All to deselect all the roles.
  3. Click the Export Configurations button to export the specified configuration information that you have selected in the JSON format.

Importing configurations

  1. Click Settings and in the Application Editor section, click Configuration Manager.

  2. On the Configuration Manager page, click the Import Configuration tab.
    Note: To import module configurations into FortiSOAR™ the configurations file must be in the JSON format.
    You will also see a Keep Existing Fields By Default checkbox on the Import Configuration page. If you select this option, then fields that are present in existing modules will be retained. This option does not affect new modules, i.e., modules that do not already exist.
    Configuration Manager - Import Configurations

  3. Before you can import any configuration, you must ensure that all staged changes are either published or reverted. The Import Configuration tab displays a warning that displays which module(s) have been changed and not published, as shown in the following image:
    Configuration Manager - Importing modules Warning Page
    Click the Review Changes in Editor button to open the module editor and review the changes in the Module Editor. After reviewing the changes, you can choose to Publish the changed modules and then import the modules. Else, you can also choose to revert the changes made in the module by clicking the Revert All Changes button and then import the modules (if required).

  4. Drag and drop the JSON file, or click the Download icon and browse to the JSON file to import configurations into FortiSOAR™.
    If the JSON format is incorrect, FortiSOAR™ displays an error message and not import the file.
    If the JSON format is correct, FortiSOAR™ imports the configurations and displays details of what is being imported.
    Configuration Manager - Importing modules
    Click Clear File to clear the imported JSON file details from Import Configuration
    FortiSOAR™ displays the count of all configuration items like SVTs, dashboards, roles along with picklists and modules that are going to be imported. If you are importing a new module, then FortiSOAR™ displays a Module will be added message. For example, in the above image, Artifacts is a new module that you are importing. If you are importing configuration for an existing module, then FortiSOAR™ displays a Module already exists. Will merge the new module with the old one. For example, in the above image, Alerts is an existing module that you are importing.
    Click the Show Picklists link to display the picklists details that are going to be imported, such as which picklist are going to be replaced or added after the import.
    You can choose not to import a picklist, and retain the current existing picklist, by clicking the red cross in the picklist row.
    Import Configuration - Show Picklists
    Click the Show Module Attributes link to display information module attribute details that are going to be imported. Module attribute details display the following field details:
    Configuration Manager - Importing Configuration: Show Module Attributes link
    Module attribute details include information about fields such as which fields are replaced and which fields are retained, and which fields are going to be created. Users can also decide what they want to do with fields that are different in the existing modules and in the configuration that you want to import by selecting options such as Keep old version, or Delete field, or Replace with new version, which are present in the Actions column.
    You can choose to sort how the fields are displayed in the grid by clicking the Sort drop-down list. The Sort drop-down list has the Default, A-Z, or Z-A options.

    • No Change (Identical Field Found): Fields that present in both the configuration that you want to import and in the existing module and which have identical properties in the configuration that you want to import and in the existing module. Available user actions are Keep field or Delete field.
      Note: Delete field will delete the field from the mmd file.
    • Replace (Matching Field Found): Fields that are present in both the configuration that you want to import and in the existing module, but which have different properties in the configuration that you want to import and in the existing module. These are fields that a user can and ideally, should replace with the newer version of the field. Available user actions are Replace with new version, Keep old version, or Delete field.
    • Keep Existing (Matching Field Found): Fields that are present in both the configuration that you want to import and in the existing module, but which have different properties in the configuration that you want to import and in the existing module. These are fields that a user should not replace, for example, in cases where the change made to the field resulted in an Unsupported type conversion and which could result in the Publish failing. Available user actions are Keep old version or Delete field.
      This Keep Existing option is also present in cases of fields that are referenced in the existing module and therefore must not be changed. The Action column, in this case, is read-only and cannot be changed by users. This Keep Existing option will also be present for system fields, whose properties cannot be changed by the user. An example of a system field would be the First Name field in the People module. In this case, as well the Action column will be read-only and cannot be changed by users. For more information on system fields, see Module Editor.
      Note: The name and properties of the Lookup (One to Many or One to One), Multiple Relationship (Many to Many), and Multiple Relationship (Many to one) fields must not be changed once they have been defined. For example, the Alerts module contains a Multiple Relationship (Many to Many) with the Indicators field, and if in the configuration that you are importing the name of this field is changed to Indicator1 then the new field Indicator1 will not be imported.
    • Create (New Field Found): Fields that are present only in the configuration that you want to import, i.e., fields that are newly added to the configuration. Available user actions are Create field or Ignore field.
      Note: If you select Ignore field then the newly added field is not included in the mmd when you import the configuration.
    • Delete (No Match Found): Fields that are present only in the existing module and not in the configuration that you want to import, i.e., fields that are deleted from the configuration. Available user actions are Keep old version or Delete field.
  5. The import details include details about what configurations are being imported and also Log messages that defines what changes will be made to your configuration after the import. Once you have reviewed the import details displayed by FortiSOAR™, click Install & Publish to copy and publish the configuration into your FortiSOAR™ environment.
    FortiSOAR™ will display a warning message asking to confirm whether you have reviewed the changes:
    Configuration Manager - Warning message before publishing the imported module
    Click I have reviewed the changes - Publish on this dialog to copy and publish the configuration into your FortiSOAR™ environment. FortiSOAR™ will then display, a Model Metadata added. Publishing changes... message and publishes the newly imported module to make the module available to all users in your environment.
    Configuration Manager - Publishing the imported module

Note: If there are any issues with the configuration that you are trying to import the Publish operation fails. In this case, there is no change to your existing module configuration. However, changes related to configurations of components other than modules, such as dashboards, picklist, or roles are imported, and if you require to update them, then those changes will have to be done manually.

Points to be considered while using Configuration Manager

  • If you have edited a picklist on an environment (Env)1 and you import the Env1 configuration into Env2, in this case, the edited picklist items will be replaced.
  • If you have added a field, say test1, to Env1 and added a field, say test2, to Env2, to the Alerts module in both environments. Now, if you export the Alerts module from Env1 and import the Alerts module to Env2, then the Alerts module in Env2 gets completely overridden, i.e., the Alerts module in Env2 will now only contain the test1 field, and the test2 field gets overridden.
    You can also select the Keep Existing Fields By Default check box to retain fields that were present in an existing module but which are not present in the exported (new) module.