# Servicenow

Connecting ServiceNow gives SureCloud read access to your ServiceNow instance's risk records, change requests, incidents, and task tables. SureCloud monitors open risk and remediation items to verify that findings are being tracked and progressed through defined workflows, reads change management records to provide evidence of change control activity, and collects incident data to support operational security evidence requirements. SureCloud can also push evidence task notifications into ServiceNow as part of automated evidence collection workflows.

{% hint style="info" %}
SureCloud connects to ServiceNow using OAuth 2.0 where supported, or Basic Authentication with a dedicated service account for instances where OAuth has not been configured. OAuth 2.0 is the preferred method and is supported on all current ServiceNow releases.
{% endhint %}

## Authentication and setup

{% tabs %}
{% tab title="OAuth 2.0 (recommended)" %}
{% stepper %}
{% step %}

#### Create an OAuth application registry in ServiceNow

In your ServiceNow instance, navigate to **System OAuth → Application Registry → New → Create an OAuth API endpoint for external clients**.

Configure the following:

* **Name**: `SureCloud CCM`
* **Client ID**: auto-generated — note this value
* **Client Secret**: auto-generated — note this value
* **Redirect URL**: enter the SureCloud OAuth callback URL provided in **SureCloud → Integrations → ServiceNow → Connect**
* **Logo URL**: optional
* **Active**: checked

Click **Submit**.
{% endstep %}

{% step %}

#### Create a dedicated service account

In ServiceNow, navigate to **User Administration → Users → New** and create a user account:

* **User ID**: `surecloud.ccm`
* **First name**: SureCloud
* **Last name**: CCM
* **Email**: a monitored service account email address

Assign the following roles to the account:

| Role                              | Purpose                                                 |
| --------------------------------- | ------------------------------------------------------- |
| `itil`                            | Read access to incidents, problems, and change requests |
| `risk_manager`                    | Read access to risk records in the GRC module           |
| `sn_compliance.compliance_reader` | Read access to compliance tasks and evidence records    |

Do not assign `admin` or `security_admin` — SureCloud requires read access only.
{% endstep %}

{% step %}

#### Complete the OAuth flow in SureCloud

In SureCloud, navigate to **Integrations → ServiceNow → Connect** and provide:

* **ServiceNow instance URL** (e.g. `https://yourcompany.service-now.com`)
* **Client ID**
* **Client Secret**

Click **Connect via OAuth**. SureCloud redirects to your ServiceNow instance login. Log in as the `surecloud.ccm` service account and approve the OAuth authorisation. SureCloud stores the resulting tokens and maintains access via automatic token refresh.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Basic Authentication" %}
{% stepper %}
{% step %}

#### Create a dedicated service account

In ServiceNow, navigate to **User Administration → Users → New** and create the `surecloud.ccm` account as described in the OAuth tab above. Assign the same roles: `itil`, `risk_manager`, and `sn_compliance.compliance_reader`.

Set a strong password for the account and record it securely.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → ServiceNow → Connect (Basic Auth)** and provide:

* **ServiceNow instance URL**
* **Username**: `surecloud.ccm`
* **Password**

Click **Test Connection**, then **Save**.

{% hint style="warning" %}
If the service account password is rotated in ServiceNow, update it in **SureCloud → Integrations → ServiceNow → Edit Connection** immediately to avoid a data collection gap.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                            | Use Case                                                                       |
| --------------------------------------------------- | ------------------------------------------------------------------------------ |
| `GET /api/now/table/sn_risk_risk`                   | Enumerate risk records with status, owner, and residual risk rating            |
| `GET /api/now/table/sn_compliance_task`             | Read compliance tasks and their evidence collection status                     |
| `GET /api/now/table/change_request`                 | Read change requests with approval state, risk level, and implementation dates |
| `GET /api/now/table/incident`                       | Read incidents with severity, state, and resolution data                       |
| `GET /api/now/table/task`                           | Read remediation and audit tasks assigned to SureCloud-linked workflows        |
| `GET /api/now/table/sn_risk_risk_response_task`     | Read risk response tasks and their completion status                           |
| `GET /api/now/table/sn_compliance_policy_statement` | Read policy statements linked to compliance controls                           |
| `GET /api/now/table/sys_user`                       | Enumerate ServiceNow users; verify active account states                       |
| `GET /api/now/table/sys_user_role_contains`         | Read role assignments per user                                                 |

## Pagination

The ServiceNow Table API uses offset-based pagination via `sysparm_offset` and `sysparm_limit` query parameters. SureCloud requests pages of up to 1,000 records and increments `sysparm_offset` by `sysparm_limit` until the response contains fewer records than the page size.

```json
{
  "result": [
    {
      "sys_id": "abc123",
      "number": "RISK0001042",
      "state": "Open",
      "risk_rating": "High",
      "assigned_to": { "value": "def456", "display_value": "Alice Nguyen" }
    }
  ]
}
```

The `X-Total-Count` response header provides the total record count. SureCloud uses this to determine how many pages are required before beginning collection.

{% hint style="info" %}
SureCloud uses `sysparm_fields` to request only the specific fields required, reducing response payload size and avoiding exposure of sensitive ticket content. Full record text is not collected.
{% endhint %}

## Required permissions

| Role                              | Grants                                                         |
| --------------------------------- | -------------------------------------------------------------- |
| `itil`                            | Read incidents, problems, change requests, and tasks           |
| `risk_manager`                    | Read GRC risk records and risk response tasks                  |
| `sn_compliance.compliance_reader` | Read compliance tasks, policy statements, and evidence records |

All roles are read-only in the context of SureCloud's API calls. No create, update, or delete operations are performed.

## Polling frequency

| Data type                            | Collection interval |
| ------------------------------------ | ------------------- |
| Risk records and response tasks      | 6 hours             |
| Compliance tasks and evidence status | 6 hours             |
| Change requests                      | 6 hours             |
| Incidents                            | 4 hours             |
| User and role inventory              | 24 hours            |

## Troubleshooting

<details>

<summary>Risk records are not appearing despite the GRC module being active</summary>

Risk records in ServiceNow GRC are stored in the `sn_risk_risk` table. If this table is returning empty results, the service account may be missing the `risk_manager` role, or the GRC Risk Management plugin may not be installed on the instance.

In ServiceNow, navigate to **System Applications → All Available Applications** and confirm the **GRC: Risk Management** plugin is installed. Then verify the `surecloud.ccm` account has the `risk_manager` role in **User Administration → Users → \[surecloud.ccm] → Roles**.

</details>

<details>

<summary>OAuth token refresh is failing after initial setup</summary>

ServiceNow OAuth refresh tokens expire after a period of inactivity (default 100 days on most instances). If the token has expired, SureCloud will fail to refresh it and data collection will stop.

Re-authorise the connection via **SureCloud → Integrations → ServiceNow → Reconnect** and complete the OAuth login flow again to issue a fresh set of tokens.

</details>

<details>

<summary>Compliance tasks are returning but evidence status fields are empty</summary>

Evidence status fields on compliance tasks require the `sn_compliance.compliance_reader` role. If these fields are present in ServiceNow but absent in SureCloud, confirm the role is assigned to the `surecloud.ccm` account.

Additionally, confirm that the `sysparm_fields` parameter in SureCloud's query includes the evidence-related fields. Contact SureCloud support if specific field names need to be added to the collection configuration.

</details>

<details>

<summary>Change requests from specific assignment groups are missing</summary>

By default, ServiceNow applies data access controls based on the viewing user's group memberships and ACL rules. If the `surecloud.ccm` service account is not a member of specific assignment groups, change requests scoped to those groups via row-level ACLs may be hidden.

In ServiceNow, navigate to **System Security → Access Control (ACL)** and check whether the `change_request` table has row-level ACLs restricting read access to group members. If so, add the `surecloud.ccm` account to a group that provides read access, or adjust the ACL to include the `itil` role as a sufficient condition.

</details>

<a href="https://developer.servicenow.com/dev.do#!/reference/api/latest/rest/c_TableAPI" class="button secondary">ServiceNow Table API reference</a> <a href="https://docs.servicenow.com/bundle/washingtondc-platform-security/page/administer/security/concept/c_OAuthApplications.html" class="button secondary">ServiceNow OAuth application setup guide</a>


---

# Agent Instructions: 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:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/servicenow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.