Create an incident field

Create custom incident fields in Cortex XSOAR.

Incident fields are used to accept or populate incident data coming from incidents. These fields are added to incident layouts and are mapped using classification and mapping.

Creating incident fields is an ongoing process. You can create fields from information ingested from third-party integrations. As you learn more about your needs and the capabilities of your third-party integrations, you can continually add new fields to capture the most relevant information.

When investigating an incident, an analyst can easily add relevant information to the fields in the layout. Incident fields can be populated by incident team members during an investigation at the beginning of the investigation or before closing the investigation.

Note

In the CLI, you can set and update all system incident fields using the setIncident command, of which each field is a command argument.

Field types

You can create the following field types:

Field Type	Description
Attachments	Enables the user to add an attachment, such as .doc, malicious files, reports, and incident images.
Boolean	Checkbox
Date picker	Adds the date to the field.
Grid (table)	Include an interactive, editable grid as a field type for selected incident types or all incident types. To see how to create a grid field and to use a script, see Incident field trigger scripts. When you select Grid (table), you can format the table and determine if the user can add rows.
HTML	Create and view HTML content, which can be used in any incident type. Note The following HTML tags are not permitted: blockquote, del, dd, div, dl, dt, fieldset, form, h1, h2, h3, h4, h5, h6, hr, iframe, ins, li, math, noscript, ol, pre, p, script, style, table, ul, address, article, aside, canvas, details, dialog, figcaption, figure, footer, header, hgroup, main, nav, output, progress, section, video. The following CSS tags are not permitted: background-color, text-align, font-size, font-family, font-weight, color, line-height, border-style, border, page-break-inside, tablelayout, padding, background-size, display, padding-top, padding-right, padding-bottom, padding-left, text-size-adjust, break-inside, word-break, width, height, -ms-text-size-adjust, -webkit-text-size-adjust.
Long text	Long text is analyzed and tokenized, and entries are indexed as individual words, enabling you to perform advanced searches and use wildcards. Long text fields can't be sorted and used in graphical dashboard widgets. While editing a long text field, pressing Enter will create a new line (case is insensitive). Add a placeholder, if required.
Markdown	Add markdown-formatted text as a Template that will be displayed to users in the field after the indicator has been created. Markdown lets you add basic formatting to text to provide a better end-user experience.
Multi select / Array	Select the following options: Multi-select from a (static) pre-filled list. An empty array field for the user to add one or more values as a comma-separated list. Add a placeholder, if required.
Number	Can contain any number. Default is 0.
Role	Role assigned to the incident. Determines which users (by role) can view the incident.
Short Text	Short text is treated as a single unit of text and is not indexed by word. Advanced search, including wildcards, is not supported. Short text fields are case-sensitive by default, but can be changed to case-insensitive when creating the field. While editing a short text field, pressing Enter will save and close. Maximum length 60,000 characters. Recommended use is one-word entries. Examples: username, email address, etc.
Single select	Select a value from a list of options. Add comma-separated values.
Tags	Accepts a single tag or a comma-separated list, not case-sensitive. Add a placeholder, if required.
Timer/SLA	View how much time is left before an SLA becomes past due, as well as configure actions to take if the SLA does pass. Note Incidents sorted using an SLA/Timer field are sorted by the due date of the SLA field.
URL	Add a URL when completing the field.
User	A user in Cortex XSOAR.

Note

Cortex XSOAR has a limit of 1000 incident fields, including system fields, fields you create manually, and any incident fields in installed content packs.

How to create a field

1. Select Settings & Info → Settings → Object Setup → Incidents → Incident Fields → New Field.

   To edit an existing incident field, right-click the field name and select Edit.
2. Select the relevant field type.
3. Add the following information:

   Parameter	Description
   Mandatory	If selected, this field is mandatory when used in a form.
   Field Name	A meaningful display name for the field. After you type a name, you will see below the field that the Machine name is automatically populated. The field’s machine name is applicable for searching and the CLI. Note If you try to create a new incident field with a name that already exists in the system, such as Account, you may receive a message like this: [Could not create incidentfield with ID '' and name 'Account'.Field already exists as a builtin field (100709)]. If so, select a different name as the incident field is already reserved for system use. You should not create a custom field named reason as it is a saved keyword in the tenant.
   Tooltip	An optional tooltip for the field.

4. In the Basic Settings tab, define the values according to the selected field type.

   Parameter	Description
   Placeholder	Optional text to display in the field when it is empty. This text will appear in the layout, but not in the created incident. Available for Short text, Long text, Multi-select / Array, and Tags.
   Values	A comma-separated list of values that are valid for the field.

5. If selecting a TImer/SLA field, define the following:

   Parameter	Description
   SLA	Determine the amount of time this item needs to be resolved. If no value is entered, the field serves as a counter.
   Risk Threshold	Determine the point in time at which an item is considered at risk of not meeting the SLA. By default, the threshold is 3 days, which is defined in the global system parameter.
   Run on SLA Breach	In the Run on SLA Breach field, select the script to run when the SLA time has passed. For example, email the supervisor or change the assignee. Note Only scripts to which you have added the SLA tag appear in the list of scripts that you can select.

6. If you are creating a Grid (table) field, in the Grid tab, define the following values.

   • To enable users to add/remove rows in the grid, select the User can add rows field. If selected, the user can add rows but not columns.
   • Manage rows and columns. You can move the columns and add/delete rows and columns (using the + and - signs). How you design the grid determines how it appears to users.
   • Configure each column by clicking the settings button in each column. Add the column name, select whether the column is mandatory, and the field type. If you select Lock, the value for that field is static (not editable). If you do not select the Lock checkbox (default), users can perform inline editing.
7. In the Attributes tab, define the following:

   Field	Description
   Script to run when field value changes	The script dynamically changes the field value when script conditions are met. For a script to be available, it must have the field-change-triggered tag when defining the script. For more information, see Incident field trigger scripts.
   Run the field triggered script after the new field value is saved	When configuring a field trigger script, you have the following options: Unchecked (recommended for incident modification) Leave unchecked for the script to execute before the incident is stored in the database. This enables the script to modify the incident field values using commands like !setIncident or other functions, such as demisto.set. Useful in most cases, including performing validations and starting and stopping Timer/SLA fields. Checked The script executes after the incident is stored in the database. This mode is intended for actions that use the new field value but do not change the incident itself (such as logging data to an external service). Note If you check Run the field triggered script after the new field value is saved: Inability to modify an incident The script cannot modify any incident field, including the field that triggered the script or any other custom field. setIncident Any attempt within the script to use demisto.executeCommand("setIncident") (for example, to update a custom field with a new value) does not update the context data. The War Room may incorrectly show an entry suggesting the field value was changed.
   Field display script	Determines which fields display in forms, as well as the values that are available for single-select and multi-select fields. For more information, see Create Dynamic Fields in Incident Forms.
   Add to all incident types	Determines for which incident types this field is available. By default, fields are available to all incident types. To change this, clear the Add to all Incident types checkbox and select the specific incident types to which the field is applicable. For example, you may want to limit the field to Access, Malware, and Network incident types.
   Default display on	Determines at which point the field is available. For more information, see Incident Field Examples.
   Edit Permissions	Determines whether only the owner of the incident can edit this field.
   Indexing Make data available for search	Determines if the values in these fields are available when searching. Note In most cases, Cortex XSOAR recommends selecting this checkbox so that values in the field are available for indexing and querying. However, in some cases, to avoid adverse effects on performance, you should clear this checkbox. For example, if you are ingesting an email to an email body field, we recommend that you not index the field.

8. Save the field.

   If you subsequently edit the field, you can select Don't show in the incidents layout. If selected, the incident field does not appear in the layout, but the data is displayed in the context data.
9. Add the field to an incident layout.
10. (Optional) In the incident type, map the incident field, so the incident field is automatically updated, without the analyst having to change it.

Incident field examples

The following section shows several examples of common fields used in real-life incidents.

False positive

Below is an example of a mandatory False Positive field, which will be completed when the incident is closed. The Field can have a value Yes or No. The Administrator can query or run a report based on this field. After this field is added, all incidents need to complete this field before an incident can be marked closed.

new-incident-field-basic.png

new-incident-field-attributes.png

SLA fields

The following SLA field can be used to trigger a notification when the status affecting the SLA of an incident changes. In this example, if the SLA is breached, an email is sent to the owner's supervisor.

sla-field.png

Incident field trigger scripts

Incident fields can be associated with trigger scripts that check for field change conditions and take actions based on the change. These scripts can perform any action, such as dynamically changing the field value, notifying the responder when an incident severity has been changed, or when the conditions are met. For example, the ChangeRemediationSLAOnSevChange script changes the Remediation SLA of an incident, if the severity of the incident changes for any reason.

Scripts can be created in Python, PowerShell, or JavaScript on the Scripts page. To use a field trigger script, you need to add the field-change-triggered tag when creating the script. You can then add the script in the Attributes tab, when you edit or create an incident field. If you did not add the tag when creating the script, it cannot be selected, until you add the tag.

Cortex XSOAR comes out-of-the-box with field change scripts in the Scripts page, such as:

• ChangeRemediationSLAOnSevChange: Changes the remediation SLA once a change in incident severity occurs.
• emailFieldTriggered: Sends an email to the incident owner when the selected field is triggered.
• StopTimeToAssignOnOwnerChange: Stops the Time to Assignment SLA field, as soon as an owner was assigned to an incident.

A common use case is to create a script that only allows automated changes by a playbook not manual changes by a user.

args = demisto.args()
user = args["user"]
if user:
    demisto.executeCommand("setIncident", {args["cliName"]: args["old"]})

The script checks who made the change using the user field. The cliName argument returns the field name, so that it can be attached to multiple incident fields, and block changes to them, without the need to have a different script for each field.

If you want the script to change the incident name field and context data, run the following command:

execute_command("setIncident", {"name": incident_name, "id": incident_id})

See the following video about how to create and add scripts to an incident layout. Dynamic Sections

Incident field trigger script arguments

Incident field trigger scripts have the following triggered field information available as arguments (args):

Argument	Description
associatedToAll	Whether the field is associated with all or some incidents. Value: true or false.
associatedTypes	An array of the incident 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 XSOAR defined field.
type	The field type.
unmapped	Whether it is not mapped to any incident.
useAsKpi	Whether it is being used for tracking KPI on an incident page.
user	The username of the user who triggered the script.
validationRegex	Whether there is a regex associated for validation the values the field can hold.

Script limitations

• Trigger scripts can't close incidents.
• Post-processing scripts can modify an incident, but if a modified field has a trigger script, it is not called.
• Incident modifications executed within a trigger script are only saved to the database after the modifications are completed.

Best practices

• Fields that can hold a list (related incidents, multi-select/tag/role type custom fields) will provide an array of the delta. For example, if a multi-select field value has changed from ["a"] to ["a", "b"], the new argument of the script will get a value of ["b"].
• Incident field trigger scripts run as a batch. This means that if multiple incidents are changed in the same way and are set to trigger the same action, it will happen in one batch.
• When writing incident field trigger scripts, avoid scenarios that call the scripts endlessly (for example, a change in field A triggers script X, which changes field B's value, which in turn calls script Y, which changes field A's value).

Add an incident field trigger script to an incident field

After creating an incident field trigger script in the Scripts page in Python, PowerShell, or JavaScript, you can then associate it with an incident field.

1. Go to Settings & Info → Settings → Object Setup → Incidents → Fields.
2. Select the incident field and click Edit.
3. In the Attributes tab, under Script to run when field value changes, select the desired incident field trigger script.

   Note

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

Field-change-triggered with Single Select or Multi Select types

1. Go to Settings & Info → Settings → Object Setup → Incidents → Fields.
2. Click New and create a new Incident field of one of the following types:

   • Single select
   • Multi-select
3. Click Basic Settings and in the Values section set the values you want to see in the incident layout dropdown list for this field.

   For example, instance1_id,instance2_id,instance3_id,instance4_id,instance^,id.
4. Click Attributes and in Script to run when field value changes, select the script.

   Example 3.

   This is an example of a single select script.

   # The custom mapping made for the field
   mapping_dict = {
       'instance1_id' : '123456',
       'instance2_id' : '12340987',
       'instance3_id' : '79874534',
       'instance4_id' : '90927834',
       'instance5_id' : '4543452',
   }    
       
   val = demisto.args()['new'] # when the script will be triggered this field will hold the new value chosen by the user.
   mapped_val = mapping_dict.get(val, val)  # getting the value from the map.
   execute_command('setIncident', {'customFields' :{'Single_select_field_example': mapped_val}}) # set the new incident mapped field

   Example 4.

   This is an example of a multi-select script.

   mapping_dict = {    
       'low' : '1',
       'medium' : '2',
       'high' : '3',
       'critical' : '4',
   }
       
   vals = argToList(demisto.args()['new']) # The new value from the user.
   mapped_list = [mapping_dict.get(v, v) for v in vals]
   execute_command('setIncident', {'customFields' : {'multi_select_field_example': mapped_list}})

   Note

   • When creating the script, in the Tags section, type field-change-triggered.
   • Choose the name of your custom fields to replace ‘Single_select_field_example’ or ‘multi_select_field_example’ in the examples above.
5. Go to Settings & Info → Settings → Object Setup → Incidents → Layouts and add the new incident field to an existing layout or create a new layout.
6. In the incident layout edit page, click Fields and Buttons and drag the new incident field you created to the layout.
7. Save the version.

   In the layout display, you will see the values you set in step 3.

   

   new-section.png
8. Select one of the values. The layout will update with the mapped value as set on the script related to the incident field.

Use scripts with a grid field

You can use scripts to manipulate and populate data in the Grid field. In this example, you want analysts who can add comments for the incident during their shift and use a script to automatically populate the Date Logged column with the current date when a user adds a new row to the grid.

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 setIncident 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("setIncident", 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.

   Note

   Ensure that User can add rows is selected.
4. Add the grid field to a layout, which is attached to an incident type.

Add a row to a grid

During playbook execution, if a malicious finding is discovered you may want to add that finding to a grid. You can use a script in the playbook to add a new row to the grid with the malicious finding.

This is a Python script, which 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 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("setIncident", { 'customFields': val }))

Incident field changes using SLA scripts

You can create scripts that perform specific actions when the SLA is breached in an incident field. For example, you can use the SendEmailOnSLABreach script that sends an email to specific users when the script is triggered. For more information, see Automate changes to incident fields using SLA scripts.

Create dynamic fields

Dynamic fields can display different data depending on the field value. You can control which fields display in an incident layout, new/edit, and close forms, and which values display for single-select and multi-select fields. You create a script on the Scripts page and then add the script to a field. Scripts support JavaScript, Python, and PowerShell.

Dynamic fields are useful in the following scenarios:

• You want specific values to appear in a field when the value of another field is different. For example, if the value in the Owner field is Admin, the values in the assignee field should be Jane, Joe, or Bob. If the value in the Owner field is anything else, the values in the assignee field should be Mark, Jack, or Christine.
• You can use display scripts to change the value displayed in single-select or multi-select fields in the layout. The field displays a list of options, but when selected, the field may show a different value in the layout than the one selected. For example, in a single-select field, select an incident from a list of incident names, but the field is populated with the incident ID (not the name) of the related incident.
• When assigning an incident to a user, you want to see only relevant data according to the user’s role.

1. Create a script.

   1. Go to the Scripts page and select New Script.
   2. Give the script a descriptive name.
   3. Enter a useful description.
   4. Under Tags, select field-display.

      This tag must be applied for the script to be available in the field you want to add the script.
   5. Write the script.

      Cortex XSOAR comes out-of-the-box with the hideFieldsOnNewIncident field-display script, which hides the incident field for new incidents, but appears when editing an incident.

      The field script contains the following.

      Name	Description
      demisto.incidents	The incident in which this script is running.
      field	The field attributes. Add metadata to the field, such as cliName, type, select values, etc. For example, [‘field’] [‘cliName’] is the machine learning name of the field.
      formType	Enables Cortex XSOAR to process the script in the new, edit, close incident forms. For example, you may want the field to appear in the close form and not in the edit form.
      incident.get (‘field’)	The field within the incident. For example, incident.get.(‘owner’) retrieves the owner field. If you create a custom field, you need to change this to CustomFields. For example, for the incidentclassification custom field, type: if incident.get('CustomFields').get('incidentclassification') .
      demisto.results	The results to return.
      currentUser	Specifies the current user. For example, if you want the script to check on a role assigned to user and display the appropriate output, type the following: demisto.executeCommand("getUserByUsername", {"username": demisto.args()["currentUser"] }) Add the information that you want to display according to the user roles.

2. Create an incident field.

   1. Select Settings & Info → Settings → Object Setup → Incidents → Incident Fields → New.

      If you want to add the script to an existing field, select the field and click Edit.
   2. Under Field Type, select the field type. For example, Single select.
   3. Under Field Name, enter a descriptive name.
   4. Under the Attributes tab, in the Field display script field, select the script you created in step 1.
   5. Complete the remaining field definitions Save the field.

Change field values according to groups

The following example shows how to create a script for the Assignee field, which shows different values depending on the values in the Owner field. If the Owner is defined as admin, and the list of available assignees includes one group. If the Owner is defined as anything else, the list of available assignees includes a different group.

1. In the Scripts page, copy the hideFieldsOnNewIncident and name it changeAsigneesPerOwner.
2. In the Description field, enter the following:

   Changes values available in the Assignees field based on the person defined as the owner.
3. Under Tags, add the field-display tag.
4. For the script, type the following:

   incident = demisto.incidents()[0]
   field = demisto.args()['field']['cliName']
   if incident.get('owner') == 'admin':
       demisto.results({'hidden': False, 'options': ['jane','joe', 'bob']})
   else:
       demisto.results({'hidden': False, 'options': ['mark','jack', 'christine']})

   where

   • demisto.incidents is the incident in which the script is running.
   • incident.get(‘owner’) is the field within the incident.
   • demisto.results tells us whether to hide the field or not, and which values should appear in the field. When the owner field is Admin, the values are Jane, Joe, Bob. When the **owner**owner is anyone else, the values are Mark, Jack, Christine.
5. Select Settings & Info → Settings → Object Setup → Incidents → Incident Fields → New .

   • Name the field Assign To:.

     The Values field in the Basic Settings tab has been left blank because we hard-coded the values in our script.
   • Under the Attributes tab, in the Field display script field, select the changeAsigneesPerOwner script we created above.
   • Fill in the rest of the field definitions as desired and click Save.
6. Add the field to an incident layout.
7. Create an incident to see what happens when the Owner is set to Admin and when the Owner is set to anything else.

Hide a field based on context data

In this example, you need to hide a field in the new incident form but display the field when editing the form. You also set field values for a multi-select field in the case of an existing incident.

Before you begin, download the GDPR content pack.

In this example, use the hideFieldsOnNewIncident out-of-the-box script.

incident = demisto.incidents()[0]
field = demisto.args()['field']
formType = demisto.args()['formType']
if incident["id"] == "":
    # This is a new incident, hide the field    
    demisto.results({"hidden": True, "options": []})
else:    
    # This is an existing incident, we want to show the field, to know which values to display    
    options = []
    # The field type includes the word select, such as Single select or Multi select
    if "Select" in demisto.get(field, "type"):
        # take the options from the field definition
        options = demisto.get(field, "selectValues")
    demisto.results({"hidden": False, "options": options})

1. Go to Settings & Info → Settings → Object Setup → Incidents → Incident Fields.
2. Select the Malicious Cause (if the cause is a malicious attack) field and click Edit.
3. Under the Field display script field, select the hideFieldsOnNewIncident script and click Save.
4. Go to the Incidents page and click New Incident.
5. Under the Type field, select GDPR DataBreach.

   Scroll down and note that under Mandatory Information, there is no Malicious Cause field.
6. Click Create New Incident to save the incident.
7. Select the incident you just created and click Edit.

   Scroll down to the Mandatory Information section and note that the Malicious Cause field appears and the options for the field are retrieved from the initial field definition.

Troubleshoot incident fields

Troubleshoot conflicts with custom incident fields

When trying to download a content update, you may receive the following message:

Warning: content update has encountered some conflicts

This occurs when a content update has an incident field with the same name as a custom incident field that already exists in Cortex XSOAR.

To resolve this issue, perform the following steps:

Click Install Content to force the update and retain your custom incident field. The content update will install without the system version of the incident field.

Troubleshoot closing a case incident after changing the field type

After deleting a field of type Grid (table) and creating a new field of another type (string, long text, etc.), you may receive the following error when trying to close or update an incident:

Cannot convert type []interface {} of '[map[] map[]]' to type string, field: sourceip (8902)

This error occurs with field type changes, if the fields are not compatible types, such as changing the type from long text to boolean or URL to short text. If you create an incident with that field, delete the field, create a new field with the same name but a different type, and then try to close the incident with that field, the error occurs.

For example, create a field of type table/grid and associate it with an incident type. Create an incident with that field, delete that table/grid field, and create a new field with the same name but associate it with a different type (such as short text). When you try to close the incident that has that field, an error may occur.

To resolve this issue, perform the following steps:

1. Go to Settings & Info → Settings → Object Setup → Incidents → Types.
2. Select the incident type that contains the changed field.
3. Click Edit Layouts.
4. Select the tab you want to edit.
5. Add the field you changed to the layout.
6. Save the form.
7. Go to the Incidents page and select the incident.
8. Click Close if you want to close the incident or Edit if you want to edit the incident.
9. In the Custom Fields area, reset (delete) the value for the field you changed.
10. Click Close Incident or Update Incident.