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

# ITSM

> Automatically create and sync ServiceNow incidents and Jira issues from Toktra policy violations.

Toktra's ITSM integration turns policy violations into actionable tickets in your existing service management platform. Tickets are created automatically when a violation fires, and status changes in your ITSM flow back into Toktra via a webhook receiver.

## Supported platforms

<CardGroup cols={2}>
  <Card title="ServiceNow" icon="shield">
    REST API — incidents created via the Table API (`/api/now/table/incident`) with Basic authentication.
  </Card>

  <Card title="Jira Cloud" icon="trello">
    REST API v3 — issues created via `/rest/api/3/issue` with Basic authentication (email + API token).
  </Card>
</CardGroup>

***

## Configuring an ITSM connector

<Steps>
  <Step title="Open the Integrations page">
    In your Toktra dashboard, go to **Integrations → ITSM** (`/integrations/itsm`). Click **Add connector**.
  </Step>

  <Step title="Choose a platform">
    Select **ServiceNow** or **Jira** from the platform dropdown.
  </Step>

  <Step title="Enter credentials">
    Fill in the platform-specific fields described in [Required credentials](#required-credentials) below.
  </Step>

  <Step title="Set defaults">
    Enter a **Default project** (Jira project key, e.g. `SEC`) or **Assignment group** (ServiceNow) and a **Default issue type** (e.g. `Bug`, `Incident`). These are used when creating tickets from policy violations.
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. Toktra creates a low-severity test ticket in your ITSM and shows you the external ticket ID. Verify the ticket appears before saving.
  </Step>

  <Step title="Save and activate">
    Toggle **Active** on, then click **Save**.
  </Step>
</Steps>

***

## Required credentials

<Tabs>
  <Tab title="ServiceNow">
    | Field                | Description                                                                       |
    | -------------------- | --------------------------------------------------------------------------------- |
    | **Instance URL**     | The base URL of your ServiceNow instance, e.g. `https://company.service-now.com`. |
    | **Username**         | A ServiceNow user with the `itil` role and write access to the `incident` table.  |
    | **Password**         | Password for the user above.                                                      |
    | **Assignment group** | Optional. The group name to assign created incidents to, e.g. `IT Security`.      |

    ```bash title="Environment variables" theme={null}
    ITSM_SERVICENOW_INSTANCE=https://company.service-now.com
    ITSM_SERVICENOW_USERNAME=toktra-svc
    ITSM_SERVICENOW_PASSWORD=your-password
    ```

    <Note>
      Toktra uses HTTP Basic authentication (`Authorization: Basic <base64(username:password)>`). For production use, create a dedicated service account with the minimum required permissions.
    </Note>
  </Tab>

  <Tab title="Jira">
    | Field            | Description                                                                |
    | ---------------- | -------------------------------------------------------------------------- |
    | **Instance URL** | Your Jira Cloud base URL, e.g. `https://company.atlassian.net`.            |
    | **Email**        | The email address of the Atlassian account used for API access.            |
    | **API token**    | An Atlassian API token from **Account Settings → Security → API tokens**.  |
    | **Project key**  | The Jira project key where issues will be created, e.g. `SEC` or `TOKTRA`. |
    | **Issue type**   | Default issue type, e.g. `Bug`, `Task`, or `Security`.                     |

    ```bash title="Environment variables" theme={null}
    ITSM_JIRA_BASE_URL=https://company.atlassian.net
    ITSM_JIRA_EMAIL=svc-toktra@company.com
    ITSM_JIRA_API_TOKEN=your-api-token
    ```
  </Tab>
</Tabs>

***

## Automatic ticket creation

When the Toktra policy engine evaluates a violation, it automatically calls your active ITSM connector. Tickets are created with:

* **Title**: `[Toktra] <event_type>: <summary>` — e.g. `[Toktra] policy_violation: max-tokens exceeded`
* **Description**: Full JSON violation payload including user, model, provider, and policy details
* **Severity mapping**: See [Severity mapping](#severity-mapping) below
* **Labels** (Jira): `toktra`, `ai-policy`, and the severity level

Toktra records the external ticket ID and provides a direct link to the ticket in the **Incidents** page.

***

## Severity mapping

Toktra severity levels map to native ITSM priority fields as follows:

<Tabs>
  <Tab title="ServiceNow">
    | Toktra severity | ServiceNow urgency | ServiceNow impact |
    | --------------- | ------------------ | ----------------- |
    | `critical`      | 1 — High           | 1 — High          |
    | `high`          | 2 — Medium         | 2 — Medium        |
    | `medium`        | 2 — Medium         | 3 — Low           |
    | `low`           | 3 — Low            | 3 — Low           |

    ServiceNow sets the incident **priority** automatically from urgency + impact using the default priority matrix.
  </Tab>

  <Tab title="Jira">
    | Toktra severity | Jira priority |
    | --------------- | ------------- |
    | `critical`      | Highest       |
    | `high`          | High          |
    | `medium`        | Medium        |
    | `low`           | Low           |
  </Tab>
</Tabs>

***

## Bidirectional sync

When a ticket is resolved or updated in your ITSM, you can push the status change back to Toktra. Configure your ITSM to send a webhook to:

```
POST https://api.toktra.io/v1/integrations/itsm/webhook/{org_id}
```

The webhook payload should include:

```json title="ITSM webhook payload" theme={null}
{
  "external_ticket_id": "INC0012345",
  "status": "resolved",
  "resolution": "Policy configuration updated to allow this usage pattern.",
  "notes": "Reviewed by security team — false positive.",
  "updated_by": "jane.doe@company.com"
}
```

Toktra matches the `external_ticket_id` to a known ticket and updates its status in the Incidents page. Valid `status` values are `open`, `in_progress`, `resolved`, and `closed`.

<Info>
  Toktra does not currently verify an HMAC signature on inbound ITSM webhooks. Restrict access to the webhook endpoint at the network level (e.g. allowlist your ITSM's IP ranges).
</Info>

***

## Creating tickets manually

You can create an ITSM ticket for any incident directly from the Toktra **Incidents** page:

<Steps>
  <Step title="Open the incident">
    Go to **Incidents** and click the incident you want to escalate.
  </Step>

  <Step title="Create ticket">
    Click **Create ITSM ticket**. Select the ITSM connector to use if you have more than one configured.
  </Step>

  <Step title="Review and submit">
    The ticket title and description are pre-filled from the incident. Edit if needed, then click **Submit**.
  </Step>
</Steps>

You can also create ITSM tickets directly from Slack using the `/toktra-alerts` command. See the [Slack integration](/integrations/slack) page.

***

## Viewing linked tickets

All tickets created by Toktra appear in **Integrations → ITSM → Tickets** with their external IDs and direct links. The table shows ticket status as last reported by your ITSM webhook.