> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/configure-cortex-xsoar/incident-configuration/incident-customization/incident-layout-customization.md). # Incident layout customization Each incident type has a unique set of data relevant to that specific incident type, including layouts. It is important to display the most appropriate data for users. Each out-of-the-box incident comes with a layout. You can customize almost every aspect of the layout, including which tabs appear, in which order they appear, who has permission to view the tabs, what information appears, and how it is displayed. It's important to build or customize the layout so that you see the information that is relevant to the incident type. For example, in a phishing incident, you may want to see email headers, but not in an access incident. While some information might be appropriate for multiple incident types, its location in one incident may require more prominence than in another incident. You can see which incident type uses the incident layout in the **Types** tab under **Settings & Info** → **Settings** → **Object Setup** → **Incidents**. The incident layout name appears in the **Layout** column. You can edit the layouts in the **Layouts** tab. You can customize the display information including fields for existing incidents, by modifying the sections and fields for the following views: | Section | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Incident Summary |

The Incident Summary tab displays the information necessary to investigate an incident. You can customize almost every aspect of the layout, including which tabs appear, the order they appear, and who has permission. In each field or tab, you can add filters by clicking on the eye icon, which enables you to add conditions that show specific fields or tabs. For example, if an analyst decides that a Cortex XDR Malware incident is a Ransomware subtype, they may only want fields to appear that show data about the encryption method and not to show information if the Malware subtype is adware.

incident-layout-filter.png

You may also want to limit specific tabs to certain scenarios. For example, if a user clicks a phishing link, the new tab can contain relevant fields and action buttons for this scenario. You can also add dynamic fields, such as a graph of several bad indicators, their source, and severity. For more information, see Create dynamic fields.

Also, you can use queries to filter the information in the dynamic section to suit your exact needs.

| | New/Edit form | Add, edit, and delete fields and buttons to be displayed when creating or editing an incident. | | Close Form | Add, edit, or delete sections, fields, and filters, when closing an incident. | | Incident Quick View | Add, edit, and delete sections, fields, and filters in the Incident Quick view section in the incident. | {% hint style="info" %} ### Note There are several out-of-the-box layout sections and fields that you cannot remove, but you can rearrange them in the layout and modify their queries and filters. These layouts need to be duplicated or detached to make changes. We recommend copying an existing out-of-the-box incident layout so you don't miss any important information. {% endhint %}
Create an incident layout 1. Go to **Settings & Info** → **Settings** → **Object Setup** → **Incidents** → **Layouts**. You can customize the following tabs: * Incident Summary * "New/"Edit" Form * "Close" Form * Incident Quick View 2. Add a meaningful name for the layout. 3. Customize the tabs by clicking the settings wheel icon and then doing the following:

Note

You can click and drag a tab to reorder the tabs.

| Action | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Rename | You can also edit a tab’s name by clicking the tab. | | Duplicate | Copies the existing tab. | | Delete | Deletes the tab. | | Show empty fields |

The setting that you configure in the layout becomes the default value seen in the report for the specific tab, which can then be overridden.

You can also set a global default value using the UI.summary.page.hide.empty.fields server configuration, which can also be overridden for a specific tab.

| | Hide tab | Hides the tab. Rather than deleting the tab, you may want to use the tab again for future use. | | Format for exporting | Build your layout based on A4 proportions to match the format used for exporting. Selecting this option hides the tab by default, but the tab will remain available for export. | | Viewing Permissions | Select which roles can view the tabs. | | Display Filter | Add or view a filter applied to the tab. If the filters apply, the specific fields or tabs are shown in the layout. If the mandatory field is not shown in the layout, the user is not obliged to complete it. | 4. Do the following: * Drag and drop the required sections, fields, buttons, and tabs. * Customize sections and create buttons. * Add any required filters. * Create new tabs 5. In the **"New"/"Edit" Form** and **"Close" Form** tabs, drag and drop the required fields and buttons. You can also edit the Basic Information and the Custom Field sections. 6. Repeat step 3 for the **Incident Quick View** tab. 7. Save the layout, and add it to the incident type.

Note

If the incident type is attached, you need to detach or duplicate it, if you want to add the layout.

8. Create or ingest an incident to test the new layout and verify fields are populated. 9. (Optional) For a customized layout (duplicate or new layout), you can contribute it to the Marketplace. 1. In the **Layouts** page, right-click the new layout and select **Contribute**. 2. In the dialog box, select either **Save and submit your contribution** or **Save and download your contribution** for later use, which you can view in the **Contributions** tab in the Marketplace. If you select Save and submit your contribution your layout is validated and then you are prompted to submit to review. You can also view your contribution in the Marketplace.
Edit an incident layout 1. Go to **Settings & Info** → **Settings** → **Object Setup** → **Incidents** → **Layouts**. 2. Click the layout name you want to edit. You can see with the current layout, which is populated with demo data so you can see how the fields fit. 3. If editing a layout that has been installed from a content pack (the layout shows a locked icon), do one of the following: * Duplicate an incident layout To add the layout to the incident type, you need to detach the incident type and then add the layout. To duplicate an incident layout, right-click the layout name in the layouts table, and select **Duplicate**. * Detach the layout. When detached, the layout does not receive content pack updates until you reattach it. You do not need to edit the incident type, as the layout name remains the same.

Tip

While a layout is detached, it does not receive content pack updates. If you detach a layout and make changes, any changes made while it was detached are overwritten by the default values from the content pack. If you want to keep the changes and protect your changes from content pack upgrades, duplicate the incident type before reattaching the original.

To detach or reattach an incident layout, right-click the layout name in the layouts table, and select **Detach** or **Attach**. 4. Add sections, buttons, and fields, as required.
Customize sections 1. Create or edit a layout. 2. From the **Sections** tab in the **Library**, drag and drop the following sections: | Section | Description | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | New Section | After creating a new section, click the **Fields and Buttons** tab and drag and drop the fields as needed. | | Cortex XSOAR out-of-the-box sections | Out-of-the-box sections such as attachments and evidence. | | General Purpose Dynamic Section | You can add a script to the incident layout. For example, assign a script that calculates the total number of entries that exist for an incident, which dynamically updates when new entries are added to the incident. |

Note

To remove or duplicate a section, select the section, click indicator-option-pointer.png , and then select Duplicate or Remove.

3. Define section properties by clicking ![](/files/3F4kuGfUKorGaW0WdmJ4) and then **Edit section settings**.

Tip

Limit the number of incident fields to 50 in each section. You can create additional sections as needed.

You can determine how a section in the layout appears in the layout. For example, you may want a section header, or configure the fields to appear in rows or as cards. If some of the field values will be very long, use rows instead of cards. If the field values are short, you might want to use cards so you can fit more fields into a section. To add a long description in the **Description** field, click **Scrollable description** to add a scrollbar to enable the displayed information to grow to fit the content. 4. If adding the **Malicious or Suspicious Indicators** section, you can change the information that appears, by editing the **Query** field. For example, to see all indicators of type IP and with a reputation of Bad that were found by a specific source since January 2nd 2022, enter **`Type:IP and reputation:Bad and firstseenbysource:>="2021-01-02T00:00:00 +0200"`** 5. Drag and drop fields, and add any filters as required. 6. If relevant, create a new tab and repeat the steps as required.
Add a script to the layout You can add script-based content to the incident layout by adding the **General Purpose Dynamic Section** in the incident layout builder. The **General Purpose Dynamic Section** enables you to configure a section in the incident layout from a script. The script can return a simple text, markdown, or HTML, the results of which appear in the **General Purpose Dynamic Section**. You can add any required information from a script. For example, you can assign a script that calculates the total number of entries for an incident, which dynamically updates when new entries are added to an incident. You can add a custom widget to the incident page and add note information using a script. The following are examples of values that can be returned from the **General Purpose Dynamic Section** script: **Text example** `return_results()` **Markdown example** ```programlisting return_results({ 'ContentsFormat': EntryFormat.MARKDOWN, 'Type': EntryType.NOTE, 'Contents': }) ``` **HTML example** ```programlisting return_results({ 'ContentsFormat': EntryFormat.HTML, 'Type': EntryType.NOTE, 'Contents': }) ``` For the **`EntryFormat`** values see [EntryFormat](https://xsoar.pan.dev/docs/reference/api/common-server-python#entryformat) in Common Server Python functions. How to add a script to a layout Before you begin, you need to create a script. 1. Create a script. For examples of script-based widgets for layouts, see [Examples of using scripts in incident layouts](#UUID-f773dd63-9af6-acf8-b1b5-2a34227ee28e) Add the **`dynamic-section`** tag. 2. Create or edit an incident layout. 3. Drag and drop the **General Purpose Dynamic Section** into the layout area you want to appear. 4. Select the General Purpose Dynamic Section, click ![](/files/3F4kuGfUKorGaW0WdmJ4) and then click **Edit section settings**. 5. In the **Name** and **Description** fields, add a meaningful name and a description for the dynamic section that explains what the script displays. 6. In the **Automation script** field, from the dropdown list, select the script that returns data for the dynamic section.

Note

Only scripts to which you have added the dynamic-section tag appear in the dropdown list.

7. Save the section.
Create custom buttons You can add existing buttons or create buttons and then drag and drop them in the layout. To add a custom button, create a script and then add the new button to the layout and select a script. These buttons can simplify and assist an analyst in carrying out various tasks. For example, add buttons for an analyst to self-assign an incident, link or unlink an incident, close an incident as a duplicate, or generate a summary report. For fields (script arguments) that are optional, you can define whether to show them to analysts when they click on buttons. To expose an optional field, select the **Ask User** checkbox next to the script arguments in the button settings page. In the following example, add a button to the layout, which self-assigns an incident for an analyst. The Common Scripts content pack includes an **AssignToMeButton** Script. {% hint style="info" %} ### Note When creating a script for use in an incident layout, the `incident-action-button` tag must be assigned for the script to be available for custom buttons. The script that runs when an action button is clicked accepts only mandatory arguments through the pop-up window and does not provide an option for any non-mandatory arguments to be filled in when the button is clicked. It is recommended to use a wrapper script to collect and validate arguments in scenarios where there can be a combination of mandatory and non-mandatory arguments for a button. {% endhint %} In the following example, create a button to self-assign an incident for an analyst, and add it to a layout. 1. Create or edit a layout. 2. Create a new section. 3. In the **Fields and Buttons** tab, drag and drop the **New Button** into the relevant section. 4. **Click to configure**. 5. In the **Button Display Name**, enter `Assign to Me`. 6. Select a color if required. 7. In the Button Script field, add the **AssignToMeButton** script. 8. Save the Button settings and then save the layout.

Note

The Case Management - Generic content pack includes several buttons to use in a layout, such as Assign to Me, Close as Duplicate, and Link incidents. You can also see useful case management incident layouts. For more information, see Case Management - Generic content pack.

Add the layout to an incident type 1. Go to **Settings & Info** → **Settings** → **Object Setup** → **Incidents** → **Types**. 2. Select the incident type and click **Edit**. 3. In the **Layout** field, from the dropdown list, add the customized layout. 4. (Optional) For a customized layout, you can contribute it to the Marketplace. 1. In the **Layouts** page, select the new layout and then click **Contribute to Marketplace**. 2. In the dialog box select either **Save and submit your contribution** or **Save and download your contribution** for later use, which you can view in the **Contributions** tab in Marketplace. If you select **Save and submit your contribution**, your layout is validated and you are prompted to submit to review. You can also view your contribution in Marketplace.
Add incident access control fields to the layout In any SOC team, there are various roles and responsibilities. For example, you may have specific teams to deal with threats, such as threat intelligence researchers, security analysts (Tier 1), senior analysts (Tier 2), SOC leads, SOC managers, and SIEM engineers. You have various options to limit access to incidents and investigations. * Exclude access to incident actions and investigations according to roles using role-based permissions. For example, you may want to limit the ability to change the incident status, or manage the Work plan. For more information, see [Role-based permissions](/cortex-xsoar-8-on-prem/8.7/configure-cortex-xsoar/users-and-roles-management/roles-management/role-based-permissions.md). * Restrict an investigation according to team members. In an investigation, the owner of the incident can restrict the incident to team members only. Analysts can select **Restrict incident** (under Actions) to restrict an incident.

Note

If using a script, use the restrictInvestigation command. You need to specify the incident ID of the incident and set the set the Restrict argument to True to restrict the incident or set the Restrict argument to False to remove restricted from the incident.

* Limit access to investigations, by doing the following: * Limit investigations according to specific user roles You can add the **Roles** field to the layout, which enables you to restrict access to all roles other than those you have specifically added. For example, after an investigation is closed, add administrators or those with specialty roles, so only they can reopen or link incidents. The added roles have read and write permission, but all other roles do not have access (unless you have added them in the read-only field).

Note

* Give read-only access to certain user roles You add the **XSOAR Read Only Roles** field to the layout, which restricts access to the incident. When granting read-only access, the user can view the incident but not edit. For example, when an incident is in triage (phase 1), you may want all Tier-2 analysts to have read-only access, so that Tier-1 can edit the incident. When the phase changes to phase 2, Tier-1 has read-only access. Adding a team member overrides the **XSOAR Read Only Roles** field, so if you add User A, (Tier 1) as a team member, even if you assign Tier-1 as a Read only role, the user still has Read/Write access. You need to remove the user as a Team Member. Although an analyst can change the XSOAR Read-Only field manually, you can automate the process by creating a custom incident field using Incident Field Trigger Scripts, or create a script and adding a new field button.

Note

You can also run the !setIncident xsoarReadOnlyRoles=``<name of role> in the CLI, playbook, or script to set the the user role.

If you assign a role (read and write permission) and assign the same role as read only, the user still has read/write permission. You need to remove the assigned role. If you restrict the incident, the read-only role does not override the restriction. In other words, team members permission takes precedence.

### **Examples of using scripts in incident layouts** The following are examples of scripts that are supported in incident layouts:
Charts A valid result for a chart widget is a list of groups. Each group points to a single entity. For example, in bar charts, each group is a bar. A group consists of the following: * `Name`: A string. * `Data`: An array of integers. * `Color`: A string representing a color that will be used as a default color for that group. It can be the name of the color, a hexadecimal representation of the color, or an RGB color value (optional). * `Groups`: A nested list of groups (optional). Horizontal bar In this example, create a script in Python that displays a horizontal bar of the indicators by severity. After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays: ![](/files/FCC9w0cq9HsuYRdfk8sP) Vertical bar In this example, create a script in Python that displays a vertical bar of the indicators by severity. After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays: ![](/files/elx7ujwrPq3RSbB0JDHs) Stacked bar In this example, create a script in Python that displays a stacked bar showing the successes and failures on specific dates. After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays: ![](/files/gMqeBA5KGhgYK6Fl8dkK) Line chart In this example, we create a JavaScript that displays how many GitHub issues were created each week for Content, Documentation, and Platform in a line chart. After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:
Pie In this example, create a script in Python that queries and returns a pie chart. ```programlisting data = { "Type": 17, "ContentsFormat": "pie", "Contents": { "stats": [ { "data": [ 1 ], "groups": None, "name": "high", "label": "incident.severity.high", "color": "rgb(255, 23, 68)" }, { "data": [ 1 ], "groups": None, "name": "medium", "label": "incident.severity.medium", "color": "rgb(255, 144, 0)" }, { "data": [ 2 ], "groups": None, "name": "low", "label": "incident.severity.low", "color": "rgb(0, 205, 51)" }, { "data": [ 8 ], "groups": None, "name": "unknown", "label": "incident.severity.unknown", "color": "rgb(197, 197, 197)" } ], "params": { "layout": "horizontal" } } } demisto.results(data) ``` After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays indicator severity as a pie chart: ![](/files/1j3oQ70AQebCe0CpyIlw)
Duration In this example, create a script in Python that queries and returns a time duration (specified in seconds), and displays the data as a countdown clock. ```programlisting data = { "Type": 17, "ContentsFormat": "duration", "Contents": { "stats": 60 * (30 + 10 * 60 + 3 * 60 * 24), "params": { "layout": "horizontal", "name": "Lala", "sign": "@", "colors": { "items": { "#00CD33": { "value": 10 }, "#FAC100": { "value": 20 }, "green": { "value": 40 } } }, "type": "above" } } } demisto.results(data) ``` After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays the time duration: ![](/files/4o6wSmGxzH591Vft8REE)
Number This example shows how to create a single item widget that displays a number. ```programlisting data = { "Type": 17, "ContentsFormat": "number", "Contents": { "stats": 53, "params": { "layout": "horizontal", "name": "Lala", "sign": "@", "colors": { "items": { "#00CD33": { "value": 10 }, "#FAC100": { "value": 20 }, "green": { "value": 40 } } }, "type": "above" } } } demisto.results(data) ``` After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays: ![](/files/KOF9s6VOhoG0CWT3sraD)
Number Trend This example shows how to create a single-item widget that displays a number trend. ```programlisting data = { "Type": 17, "ContentsFormat": "number", "Contents": { "stats": { "prevSum": 53, "currSum": 60 }, "params": { "layout": "horizontal", "name": "Lala", "sign": "@", "colors": { "items": { "#00CD33": { "value": 10 }, "#FAC100": { "value": 20 }, "green": { "value": 40 } } }, "type": "above" } } } demisto.results(data) ``` After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays: ![](/files/u6YJJZFKDLnNpIczZct7)
Add note information This example shows how to add note information to an incident layout using a script through the API. 1. Install the Cortex REST API content pack and add a Core REST API instance. 2. Go to the **Scripts** page and add the following script: ```programlisting commonfields: id: ShowLastNoteUserAndDate version: -1 name: ShowLastNoteUserAndDate script: |2 function getLastNote(incidentID) { var body = {pageSize:1,categories:['notes']}; var res = executeCommand('demisto-api-post', {uri:'/investigation/' + incidentID, body: body}); if (isError(res[0])) { throw 'demisto-api-post failed for incidnet #'+incidentID+'\nbody is ' + JSON.stringify(body) + '\n' + JSON.stringify(res); } if (!res[0].Contents.response.entries) { return null; } var notes = res[0].Contents.response.entries; var lastNote = notes[notes.length-1]; return lastNote; } lastNote = getLastNote(incidents[0].id); if (lastNote) { md = `#### Update by ${lastNote.user} on ${lastNote.modified.split('T')[0]}\n`; md += `\n---\n`; md += lastNote.contents + '\n'; return { ContentsFormat: formats.markdown, Type: entryTypes.note, Contents: md } ; } else { return 'N/A'; } type: javascript tags: - dynamic-section enabled: true scripttarget: 0 runonce: false runas: DBotWeakRole ``` 3. Add the script to the layout and then add the layout to the incident type. 4. Go to the incident to view the note information. You can see note information, containing the last user and date. ![](/files/ubsrFWA3PT67H4TPvEg9)
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/configure-cortex-xsoar/incident-configuration/incident-customization/incident-layout-customization.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.