Issue field-triggered scripts

Configure Cortex XSIAM field-change-triggered scripts to automate issue updates, validations, notifications, and workflows.

Configure Cortex XSIAM issue fields to run scripts when field values change. Field-change-triggered scripts automate issue workflows throughout the issue lifecycle. Use them to update field values, validate changes, or notify responders when issue severity changes. Scripts can include conditions, such as a required field value.

Create issue automation scripts in Python, PowerShell, or JavaScript on the Scripts page. To use a script as a field trigger, add the field-change-triggered tag. Then add it from the Attributes tab when you create or edit an issue field. Scripts without this tag cannot be selected.

When a script is associated with an issue field, Cortex XSIAM saves field changes after the triggered script finishes. This lets you verify conditions, such as whether a field is completed, before a user resolves an issue.

During a bulk update, a field-triggered script runs in every issue where its assigned field changes.

An issue field-triggered script can modify multiple fields. If a script triggered by field A changes field B, Cortex XSIAM does not trigger a script assigned to field B.

Cortex XSIAM includes the emailFieldTriggered script. It emails the issue owner when the selected field changes. You can also create custom issue automation scripts.

This feature assumes fair and intended usage of field-triggered scripts. In cases of excessive or abusive usage, execution may be restricted or disabled. If script execution is restricted or disabled, fields are still updated, but without the results of the assigned script.

Issue field-triggered script arguments

Issue field-triggered scripts provide the following changed-field information as arguments (args):

Argument	Description
associatedToAll	Whether the field is associated with all or some issues. Value: true or false.
associatedTypes	An array of the issue types with which the field is associated.
cliName	The name of the field when called from the command line.
description	The description of the field.
isReadOnly	Specifies whether the field is non-editable. Value: true or false.
name	The name of the field.
new	The new value of the field.
old	The old value of the field.
ownerOnly	Specifies that only the creator of the field can edit. Value: true or false.
placeholder	The placeholder text.
required	Specifies whether this is a mandatory field. Value: true or false.
selectValues	If this is a multi-select type field, these are the values the field can take.
system	Whether it is a Cortex XSIAM defined field.
type	The field type.
unmapped	Whether it is not mapped to any issue.
useAsKpi	Whether it is being used for tracking KPI on an issue page.
validationRegex	Whether there is a regex associated validation for the values the field can hold.

Fields that can hold a list, such as multi-select custom fields, return the delta in an array as a new argument. For example, if a multi-select field value has changed from ["a"] to ["a", "b"], the new argument of the script gets a value of ["b"].

Assign a triggered script to an issue field

After you create an issue field-triggered script in Python, PowerShell, or JavaScript, associate it with an issue field.

1. Go to Settings → Configurations → Object Setup → Issues → Fields.

2. Right-click the issue field and select Edit.

3. In the Attributes tab, under Script to run when field changes, select the desired issue field-triggered script.

   Issue field-triggered scripts must have the field-change-triggered tag to appear in the list.

   Issue field trigger scripts are not supported for all system fields. The following fields are not supported for issue field trigger scripts and may result in failing to populate the issue layout:

   • Cases: Case ID, Cases IDs

   • Asset Fields: Asset IDs, Asset Names, Asset Classes, Asset Categories, Asset Groups, Asset Regions, Asset Providers, Asset Accounts, Asset Types

   • Other: Business Application Names, Findings

Use field-change-triggered scripts with select fields

1. Create and save a single select or multi-select script in the Scripts page.

   When creating the script, add the field-change-triggered tag in the script settings.

   This is an example of a single select script.

   # Mapping of user selection to email addresses
   owner_mapping = {
       'option1': '[e-mail]',
       'option2': '[e-mail]',
       'option3': '[e-mail]',
       'option4': '[e-mail]',
       'option5': '[e-mail]',
   }
   
   # The value selected by the user when the script is triggered
   val = demisto.args().get('new')
   
   # Get the mapped email address
   owner_email = owner_mapping.get(val, val)
   
   # Set the owner of the incident
   demisto.executeCommand('setIssue', {
       'owner': owner_email
   })

2. Go to Settings → Configurations → Object Setup → Issues → Fields.

3. Click New Field and create a new issue field of one of the following types:

   • Single select

   • Multi-select

4. Click Basic Settings and in the Values section set the values you want to see in the issue layout dropdown list for this field.

   For example, option1,option2,option3,option4,option5.

5. Click Attributes and in Script to run when field changes, select the script you created in Step 1.

6. Go to Settings → Configurations → Object Setup → Issues → Layouts and add the new issue field to an existing layout or create a new layout.

7. In the issue layout edit page, click Fields and Buttons and drag the new issue field you created to the layout.

8. Save the version.

9. Select one of the values. The layout will update with the mapped value as set on the script related to the issue field.

Use triggered scripts with a grid field

You can use scripts to manipulate and populate data in a grid field. In this example, analysts add comments to issues they work on during their shifts. The script automatically populates a column of the grid, logging the timestamp of each comment.

1. Create a script called ShiftSummariesChange. The script operates in the following phases:

   • The script gets all new rows and sets the Date Logged field to now (current day).

   • For each existing row, if the name matches, and the findings column is not updated, the Date Logged column is also updated.

   • After creating a grid field, it is saved with the new values using the setIssue command.

     var newField = args.new ? JSON.parse(args.new)  : [];
     //if line(s) added, set "datelogged" to now.
     if (oldField.length < newField.length) {
         // for each new line change date.    
         for(var i=oldField.length; i < newField.length; i++) {
             newField[i].datelogged = new Date ().toISOString();
         }
     }
     var columnName = "findings";
     // for each old line if the "columnName" has changed, change date to now.
     for(var i=0; i < oldField.length; i++) {
         if (newField[i] && oldField[i].fullname === newField[i].fullname &&
         oldField[i][columnName] !== newField[i][columnName]) {
             newField[i].datelogged = new Date().toISOString();
         }
     }
     var newVal = {};
     newVal[args.cliName] = newField;
     executeCommand("setIssue", newVal);

2. Add the field-change-triggered tag and save the script.

3. Create a Shift Summaries grid field with the following columns:

   • Full name

   • Findings

   • Status

   • Date Logged

     Select Date picker with the Lock checkbox, so the script can populate the values for that column. If a column is unlocked (default), the column values can be entered manually (by users), or by a script.

   Verify that User can add rows is selected.

Add a row to a grid

During playbook execution, if a malicious finding is discovered, you can add that finding to a grid, using a script in a playbook task.

This Python script requires two arguments:

• fieldCliName: The machine name for the field for which you want to add a new row.

• Row: The new row to add to the grid. This is a JSON object in lowercase characters, with no white space.

fieldCliName = demisto.args().get('field')
currentValue = demisto.incidents()[0]["CustomFields"][fieldCliName];

if currentValue is None:
    currentValue = [json.loads(demisto.args().get('row'))]
else:
    currentValue.append(json.loads(demisto.args().get('row')))

val = json.dumps({ fieldCliName: currentValue })
demisto.results(demisto.executeCommand("setIssue", { 'customFields': val }))

During playbook execution, if a malicious finding is discovered, you can add that finding to a grid, using a script in a playbook task.

This Python script requires two arguments:

• fieldCliName: The machine name for the field for which you want to add a new row.

• Row: The new row to add to the grid. This is a JSON object in lowercase characters, with no white space.

fieldCliName = demisto.args().get('field')
currentValue = demisto.incidents()[0]["CustomFields"][fieldCliName];

if currentValue is None:
    currentValue = [json.loads(demisto.args().get('row'))]
else:
    currentValue.append(json.loads(demisto.args().get('row')))

val = json.dumps({ fieldCliName: currentValue })
demisto.results(demisto.executeCommand("setIssue", { 'customFields': val }))