> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ServiceNow

> Create ServiceNow incidents automatically from compliance events.

The ServiceNow integration creates ITSM incidents when Verilock detects compliance events that require manual review. Incidents are assigned to the correct team with appropriate priority levels.

## Prerequisites

* A ServiceNow instance (Paris release or later)
* A ServiceNow user account with the `itil` role
* Verilock Enterprise plan

## Setup

<Steps>
  <Step title="Create a ServiceNow Developer Instance">
    If you do not have a production instance, create a free developer instance at [developer.servicenow.com](https://developer.servicenow.com). Activate the **ITSM** application.
  </Step>

  <Step title="Create an Integration User">
    In ServiceNow, navigate to **User Administration > Users** and create a new user with the `itil` and `rest_service` roles. This user will be used for API authentication.
  </Step>

  <Step title="Configure Credentials in Verilock">
    Go to **Dashboard > Settings > Integrations > ServiceNow** and enter:

    * **Instance URL**: `https://your-instance.service-now.com`
    * **Username**: The integration user's username
    * **Password**: The integration user's password
  </Step>

  <Step title="Configure Assignment Groups">
    Map Verilock event categories to ServiceNow assignment groups:

    * **Compliance events**: e.g., `Compliance Review Team`
    * **Security events**: e.g., `Security Operations`
    * **Transaction events**: e.g., `Fraud Investigation`
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify API access. Verilock will create a test incident and immediately resolve it.
  </Step>
</Steps>

## Event-to-Incident Mapping

Each Verilock event maps to a ServiceNow incident with a specific priority and category:

| Verilock Event         | Priority      | Category   | Assignment Group      |
| ---------------------- | ------------- | ---------- | --------------------- |
| `aml.match_found`      | P1 - Critical | Compliance | Compliance Review     |
| `aml.monitoring.match` | P1 - Critical | Compliance | Compliance Review     |
| `transaction.blocked`  | P1 - Critical | Fraud      | Fraud Investigation   |
| `session.declined`     | P2 - High     | Security   | Security Operations   |
| `session.completed`    | P2 - High     | Security   | Security Operations   |
| `transaction.flagged`  | P2 - High     | Fraud      | Fraud Investigation   |
| `face.duplicate_found` | P2 - High     | Security   | Security Operations   |
| `session.expired`      | P3 - Moderate | Operations | Identity Verification |

<Info>
  Priority and assignment group mappings are fully configurable from the Verilock dashboard. The defaults shown above can be overridden per event type.
</Info>

## Incident Fields

Each incident created by Verilock includes the following fields:

| ServiceNow Field        | Verilock Source                           |
| ----------------------- | ----------------------------------------- |
| `short_description`     | Event type and session/screening ID       |
| `description`           | Full event payload with applicant details |
| `category`              | Mapped from event type                    |
| `priority`              | Mapped from event type                    |
| `assignment_group`      | Configured assignment group               |
| `caller_id`             | Integration user                          |
| `u_verilock_session_id` | Session or screening ID                   |
| `u_verilock_risk_score` | Risk score (0-100)                        |

<Warning>
  Custom fields (`u_verilock_session_id` and `u_verilock_risk_score`) require a ServiceNow Update Set. Download it from **Dashboard > Settings > Integrations > ServiceNow > Download Update Set**.
</Warning>

## Example Incident Payload

```json theme={null}
{
  "short_description": "AML Match Found - aml_x7k9m2p4",
  "description": "Verilock AML screening detected a potential match.\n\nScreening ID: aml_x7k9m2p4\nApplicant: Jean Dupont\nMatch Type: PEP\nMatch Score: 92%\n\nReview: https://verilock.io/dashboard/aml/aml_x7k9m2p4",
  "category": "Compliance",
  "priority": 1,
  "assignment_group": "Compliance Review",
  "u_verilock_session_id": "aml_x7k9m2p4",
  "u_verilock_risk_score": 92
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failures">
    Ensure the integration user has `itil` and `rest_service` roles. Verify the instance URL does not include a trailing slash.
  </Accordion>

  <Accordion title="Missing custom fields">
    Import the Verilock Update Set into your ServiceNow instance. Navigate to **System Update Sets > Retrieved Update Sets** and preview/commit the update set.
  </Accordion>

  <Accordion title="Duplicate incidents">
    Verilock uses the `webhook_id` as a correlation ID. If duplicate incidents appear, check that your ServiceNow instance is responding with 2xx status codes within 10 seconds.
  </Accordion>
</AccordionGroup>