> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/workbench-setup/notifications/platform-setup/servicenow-setup-for-organization-notifications.md). # ServiceNow Setup for Organization Notifications Expel offers a notification synchronization capability for ServiceNow (synchronization refers to Workbench's ability to continuously update a ticket based on state changes in Workbench). This guide is the first step of a larger process to enable organization notifications. {% hint style="info" %} After completing the steps on this page, you will be instructed to go to [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications.md) to set up your actual notifications. {% endhint %} ## Scope and Limitations When choosing to set up this integration, remember the following: 1. Only the **IT Service Management (ITSM)** and **Security Incident Response (SIR)** modules are supported, and the steps listed in this guide apply to both. 2. This plugin **cannot** be customized. * If you are seeking customizable payloads for organization notifications, please instead utilize [webhooks](/connect-your-technology/about-integrations/webhooks-setup-for-workbench.md) or an [email ticketing system](/workbench-setup/notifications/platform-setup/ticketing-system-setup-for-organization-notifications.md). 3. ServiceNow will **not** be used to ingest your security signal for MDR purposes; it will only be used to support notifications. 4. Synchronization is only available for Workbench **Investigations** or for Investigations flagged as **Incidents**. * See the [Reference](#reference) section for more information about notification synchronization. ## Prerequisites 1. You must have a ServiceNow Administrator account with *security\_admin* privileges. 2. You must be using either the ITSM or SIR module, as these are the two supported modules for this integration. 3. The ITSM or SIR module must *already* be added and enabled on the ServiceNow account. ## Step 1: Configure ServiceNow API Access for Expel 1. [Log in to the ServiceNow instance](https://www.servicenow.com/my-account/sign-in.html) using the administrator account. 2. [Elevate your role](https://docs.servicenow.com/bundle/xanadu-platform-security/page/administer/security/task/t_ElevateToAPrivilegedRole.html) to **security\_admin**. 3. Navigate to **User Administration > Users** and select **New** in the upper right corner. 4. For the User ID field, enter "expeluser". The rest of the fields can be left blank. 5. Select **Submit**. 6. From the Users list, select **expeluser**. 7. On the User page, select **Set Password**. 8. Select **Generate**. Copy the password and save it to a safe place, as you will need it in a later step. 9. Select **Save Password**. 10. Select **Close**. 11. Still on the User page, scroll down to the **Roles** tab and select **Edit**. 12. Grant the Expel user the appropriate role, depending on your module, so that it has the required permissions to access the incidents table from the REST APIs. {% tabs %} {% tab title="ITSM Module" %} 1. Enter "incident\_manager" in the Collection field. 2. Select **incident\_manager** in the list builder and select **>** to add it to the Roles List. 3. Select **Save**. {% endtab %} {% tab title="SIR Module" %} 1. Enter "sn\_si.manager" in the Collection field. 2. Select **sn\_si.manager** in the list builder and select **>** to add it to the Roles List. 3. Select **Save**. {% endtab %} {% endtabs %} 4. Navigate to **System OAuth > Application Registry**. 5. Select **New** in the upper right. 6. Select **Create an OAuth API endpoint for external clients**. 7. Provide a **Name** for the registry. 8. The default settings can be left as is. 9. Select **Submit**. 10. On the Application Registries page, select the name of the registry you just created. 11. Copy the **Client ID** and **Client Secret** and save them in a safe place, as you will need these values in a later step. ## Step 2: Add ServiceNow as a Security Device in Workbench 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F). 2. In the side menu, navigate to **Organization Settings > Security Devices**. 3. Select **Add Security Device**. 4. In the search box, type “ServiceNow” and then select the **ServiceNow** integration. 5. Complete the fields as follows: * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName ServiceNow”; this name will display in Workbench under the Name column, and is a text string that you can filter on. * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations. * **Username and Password** - enter "expeluser" for the username, and enter the password you generated in [Step 1](#step-1-configure-servicenow-api-access-for-expel). * **Server** - enter the URL from the ServiceNow instance you configured the Expel user on in [Step 1](#step-1-configure-servicenow-api-access-for-expel). For example: . * **Client ID and Client secret** - enter the ID and secret you obtained in [Step 1](#step-1-configure-servicenow-api-access-for-expel). * **Module** - use the dropdown to select the appropriate option depending on whether you are adding an ITSM or SIR device. * **Assignment group** - this is optional and can be left blank. * **Console Access** - granting Workbench access to your ServiceNow console is optional. 6. Select **Save**. 7. Your device should be created successfully within a few seconds. A few reminders: * To check on the status, select the downward arrow for your device in the first column and choose **View details**. You can then scroll to the **Connection** section to see if your device is fully connected. * You must refresh the page to see updates. * Note that a status of "N/A" for Last successful poll is expected. * If your device does not report a healthy connection, check that the values you entered into Workbench are correct. If you need further troubleshooting, [contact Support](/support/how-to-reach-us.md). 8. In the **Integrations** tab on the [**Organization Settings**](#user-content-fn-1)[^1] page, look for a new section titled ServiceNow, and ensure it says **Enabled**. * If it you find this section and it is enabled, proceed to [Step 3: Add Your Organization Notifications](#step-3-add-your-organization-notifications). * If there is no new ServiceNow section, continue to the next step. 9. In the side menu, navigate to **Organization Settings > My Organizations** and select the name of your organization. 10. Select the **Integrations** tab. 11. Scroll to the ServiceNow section and select **Enable ServiceNow integration**. ## Step 3: Add Your Organization Notifications Now you can begin setting up your organization notifications. See [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications.md) for instructions. If you wish to enable synchronization as part of your organization notifications, see [How to Configure](#how-to-configure) in the Reference section for more information. {% hint style="info" %} For a list of default notifications, see [Default Organization Notifications](/workbench-setup/notifications/about-notifications.md#default-organization-notifications). You can edit these notifications at any time using the instructions in the linked guide above. {% endhint %} ## Reference ### Synchronization Capabilities Synchronization is only available for Incidents and Investigations. Upon creation of a ServiceNow ticket, any subsequent change or update associated with that Investigation or Incident is captured and logged as a comment on that same ticket. {% hint style="warning" %} Fields are not currently updated. {% endhint %} For example, if any of the following occurs, a comment is added to the ServiceNow ticket that was created when the Investigation/Incident opened in Workbench: * An **Expel Alert** is added to the Investigation/Incident. * A **Verify/Notify Action** is created and sent as part of the Investigation/Incident. * A **Remediation Action** is assigned, automated, or completed as part of the Investigation/Incident. When a ticket is created, the following fields are set: * **Title** - name of Workbench event (example: `[ORG-XXX] Incident created: Authentication from suspicious country`) * **Description** - includes the `URL` to the Workbench event (Incident or Investigation) and details about the event. * **Incident State** - set to `In Progress`. * **Caller** - set to `Expel Integration`. ### How to Configure There is a specific action of `has any state change` within organization notifications for the `Investigation` and `Incident` event types, and it is only supported for ServiceNow. When configuring notifications for this set of conditions, set the `notify via` destination to ServiceNow.
Image of the conditions and notify via settings.
Once saved, whenever an Investigation or Incident is updated in Workbench, comments are appended to the associated ServiceNow ticket. The comments include a URL back to the original Investigation or Incident, and details about the update. ### Supported Synchronization Events For the below events, one ServiceNow ticket is created and continuously updated throughout the lifecycle of the Investigation or Incident. | Workbench Event | State or Action | What Happens in ServiceNow | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | Incident | Created | Ticket created | | Incident |

Assigned

Closed

Downgraded

Promoted

Reopened

Remediation Action assigned/completed/failed

| Comment added to ticket | | Investigation | Created | Ticket created | | Investigation |

Alert added

Assigned

Closed

Reopened

Investigative Action created/assigned/approved/denied (this includes Verifies)

| Comment added to ticket | ### Unsupported Synchronization Events For the below events, one unique ServiceNow ticket is created for each event. For example, if configured, a new Expel Alert would yield one ServiceNow ticket. If configured, when that Expel Alert is closed, it would yield another ServiceNow ticket. | Workbench Event | State or Action | What Happens in ServiceNow | | ------------------------------------ | ----------------------------------------------------------- | -------------------------- | | Expel Alert | Created | Ticket created | | Investigative Action |

Analysis assigned

Assigned

Manual action

| Ticket created | | Notify Action | Assigned | Ticket created | | Verify Action |

Assigned

Approved

Denied

| Ticket created | | Custom Rule | Created | Ticket created | | Assembler Health Status Change |

First Time Healthy

Unhealthy

Healthy

| Ticket created | | Security Device Health Status Change |

First Time Healthy

Unhealthy

Healthy

| Ticket created | [^1]: In the side menu, navigate to Settings > Organization Settings. --- # 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://docs.expel.io/workbench-setup/notifications/platform-setup/servicenow-setup-for-organization-notifications.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.