> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/access-request/configure-itsm-integration.md). # Configure ITSM integration Integrate Access Requests with ITSM systems to track requests as ServiceNow tickets and fulfill external requests through ServiceNow, Jira, or other systems. Veza Access Requests can integrate with IT Service Management (ITSM) systems to connect access governance workflows with your existing ticketing infrastructure. ITSM integration supports two distinct capabilities: automatic ticket tracking for access requests, and external access requests that are fulfilled by an ITSM system outside of Veza. ## Overview ITSM integration serves two different use cases: * **ITSM Ticket Tracking**: When an access request is created in Veza, a ticket is automatically created in ServiceNow to track the request lifecycle. The ticket provides visibility into access requests through your existing ITSM workflows and reporting. * **External Access Requests**: Access requests that are initiated from or fulfilled by an external ITSM system. These requests use the External target type and the **External Running** state to represent work being performed outside of Veza. The external system drives state transitions through Veza API calls. These capabilities can be used independently or together, depending on your organization's workflow requirements. ## Supported ITSM systems Veza supports the following ITSM system types for integration: | ITSM Type | Ticket Creation | External Requests | Notes | | -------------- | --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ServiceNow** | Supported | Supported | Full integration with automatic ticket creation and lifecycle tracking | | **Jira** | Supported | Supported | Creates a Jira issue on approval through the Jira catalog definition type, and (unlike ServiceNow) can also create a revoke issue. Also available as an ITSM link type for external request tracking. | | **Other** | Not supported | Supported | Custom ITSM systems can use the generic link type for external request tracking | {% hint style="info" %} Automatic ticket creation is supported with **ServiceNow** and **Jira**. Jira ticket creation is configured through the Jira catalog definition type; see [Manage catalog definitions](/4yItIzMvkpAvMVFAamTf/features/access-request/manage-catalog-definitions.md). The **Other** link type is for associating externally created tickets with access requests. {% endhint %} ## Ticket creation with Jira When a request backed by a Jira catalog definition is approved, Veza creates a Jira issue and tracks its status. Veza does not provision the access itself: an administrator in the target system completes the provisioning work and resolves the issue. For the configuration fields, see [Manage catalog definitions](/4yItIzMvkpAvMVFAamTf/features/access-request/manage-catalog-definitions.md#jira). {% hint style="warning" %} **Just-in-time access with Jira**: For Jira-backed requests with a time-bound duration, the expiry clock does not start until an administrator moves the grant issue to a Done-category status. If the grant issue is not resolved, or is deleted, the request stays in progress and the time bound does not take effect. Access remains until it is revoked another way. ServiceNow-backed requests are unaffected. {% endhint %} ## ITSM ticket tracking with ServiceNow ITSM ticket tracking automatically creates a ServiceNow ticket when an access request is submitted. The ticket is linked to the access request and updated as the request progresses through the approval and provisioning workflow. ### Prerequisites Before configuring ITSM ticket tracking, an administrator must create a **ServiceNow notification integration** through the Veza Actions framework. The `notification_id` used in catalog definitions and the `tracking_notification_id` field in access requests must reference this integration's ID. For ServiceNow setup instructions (creating the API user and Veza Action), see [ServiceNow Veza Action](/4yItIzMvkpAvMVFAamTf/administration/administration/notifications/destinations/servicenow.md). After creating the integration, the notification ID is available on the Veza Action details page. ### How it works 1. An administrator creates a **ServiceNow Veza Action** (notification integration) for the target ServiceNow instance. 2. An administrator creates a **Catalog Definition** of type **ServiceNow**, referencing the ServiceNow Veza Action's notification ID. 3. A user submits an access request through the Access Catalog for a catalog item backed by the ServiceNow catalog definition. 4. After the request is approved and reaches the **Plan Selected** state, Veza creates a ServiceNow ticket using the configured notification integration. 5. The access request record is updated with an **ITSM Link** containing the ServiceNow ticket ID and URL. 6. The ticket content can include dynamic fields populated from the access request context, such as the requester, target, and custom form fields. ### Which path creates the ticket Three separate paths create an ITSM ticket, and a request takes exactly one of them. Which path runs depends on whether the request carries a catalog definition, and on whether it needs an approval. * **Direct request with `tracking_notification_id`, auto-approved**. Veza creates the ticket at submission, immediately after the request is saved. * **Direct request with `tracking_notification_id`, needing an approval**. Veza creates the ticket on the approval that moves the request to **Plan Selected**. * **Request backed by a catalog definition**. The Lifecycle Management processor creates the ticket through the catalog definition grant hook, after the request reaches **Plan Selected**. The paths do not overlap. A direct request never reaches the catalog definition grant hook, and a direct request whose ticket was already created at submission is skipped on approval, so a request never receives two tickets. {% hint style="info" %} **Auto-approved requests**: Ticket creation is tied to the Plan Selected state, not to a delay. An auto-approved request reaches Plan Selected at submission, so its ticket is created then. Auto-approval is something you configure, not the absence of configuration. It comes from an access request policy with auto-approval enabled, or from the grant-without-approval setting for an admin, an application owner, or an access profile owner. A request with no policy attached is not auto-approved. It lands in **Waiting for Approval**. Creating the ticket at submission also requires that the request carry no catalog definition, and that `tracking_notification_type` be `SERVICE_NOW` or `JIRA`. Sending `tracking_notification_id` while `tracking_notification_type` is unset or `OTHER` is rejected as a field violation. {% endhint %} ### ServiceNow Catalog Definition configuration To enable automatic ServiceNow ticket creation, create a catalog definition with the following configuration: * **Type**: ServiceNow * **Notification ID**: The ID of a configured ServiceNow notification integration. This determines which ServiceNow instance receives the ticket. * **Headline**: The ticket short description. Supports transformer syntax to inject properties from the LCM identity (for example, requester name, target resource). * **Message Body**: The ticket description. Also supports transformer syntax for dynamic content. * **Form Definition** (optional): Define custom form fields that requesters complete when submitting the request. Form field values are substituted into the headline and message body using `{$form_field.}` placeholders. {% hint style="info" %} **Ticket creation is deferred until after approval.** For a request backed by a catalog definition, the ticket is created only once the request reaches the **Plan Selected** state. The grant hook checks the state and creates nothing for a request in any other state, so a rejected request generates no ticket. This avoids creating tickets for requests that may not be approved. {% endhint %} ### Retry behavior and failure handling ITSM ticket creation retries transient failures with exponential backoff. Veza retries up to 3 times, waiting 5, 10, and 20 seconds between attempts. The same retry configuration applies to both ServiceNow and Jira ticket creation. Veza treats a failure as transient, and retries it, when the ITSM system returns a 5xx status, `408 Request Timeout`, or `429 Too Many Requests`, or when the error carries no recognized status code. It treats a failure as permanent, and does not retry it, for any other 4xx status and for a `notification_id` that does not resolve to an existing Veza Action. {% hint style="warning" %} **Failure behavior differs by request type**: For ServiceNow catalog definition requests, ticket creation failure causes the access request to fail (ticket creation IS the provisioning step). For direct API requests using `tracking_notification_id`, ticket creation failure is recoverable: the access request proceeds but the ITSM link is not populated. {% endhint %} ### ITSM link fields When a ServiceNow ticket is created, the access request is updated with an ITSM link containing: | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------ | | `type` | The ITSM system type (`SERVICE_NOW`, `JIRA`, or `OTHER`) | | `id` | The external ticket identifier (for example, the ServiceNow `sys_id`) | | `link_url` | A direct URL to the ticket in the external system | | `tracking_notification_id` | The notification integration ID used for ticket creation (maps to "Veza Action" in the UI) | | `status` | The current ticket status from the ITSM system | ## External Access Requests External access requests represent work that is initiated from or fulfilled by an ITSM system outside of Veza. Unlike standard access requests where Veza provisions access directly, external requests delegate fulfillment to the external system and track the outcome through API callbacks. ### External request state flow External access requests follow a specific state progression: ``` Waiting for Approval --> Plan Selected --> External Running --> Completed --> Rejected --> Errored ``` 1. **Waiting for Approval**: The external access request is created via the `CreateExternalAccessRequest` API and immediately enters this state. If an Access Request Policy is configured, the request goes through the standard approval workflow. 2. **Plan Selected**: After approval (or immediately if auto-approved), the request is ready for external fulfillment. 3. **External Running**: The external system signals it has started processing the request. This state indicates that work is actively being performed outside of Veza. 4. **Terminal states**: The external system reports the final outcome: * **Completed**: The request was fulfilled successfully. * **Rejected**: The external system rejected the request. * **Errored**: The request failed during external processing. {% hint style="info" %} **State transition ordering**: The Mark endpoints do not enforce a strict state progression. An external system can call any Mark endpoint from any intermediate state. For example, calling `MarkCompleted` without first calling `MarkRunning` is accepted. {% endhint %} ### Creating External Access Requests External access requests are created through the `CreateExternalAccessRequest` API endpoint: ``` POST /api/private/lifecycle_management/external_access_requests ``` The request includes standard access request fields (request type, assignee, target) along with an `ITSMLink` that associates the request with an external ticket: | Field | Required | Description | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_type` | Yes | `GRANT` or `REVOKE`. Omitting it persists `UNKNOWN`. | | `reason` | No | Business justification for the request | | `datasource_id` | Yes | The LCM datasource where the request applies. Must name an existing datasource that has Lifecycle Management enabled. | | `assignee_entity_type` | Yes | Entity type of the user receiving access | | `assignee_entity_id` | Yes | Entity ID of the user receiving access | | `assignee_entity_name` | No | Display name of the user receiving access. When `identity_id` resolves, Veza uses that identity's name or email instead. | | `target_entity_type` | Yes | Entity type of the target resource | | `target_entity_ids` | Yes | IDs of the target resources | | `identity_id` | No | LCM identity ID for the request beneficiary. When supplied, it must name an existing LCM policy identity; otherwise the endpoint returns `NotFound`. | | `itsm_link` | Yes | The link to the external ticket. Only the presence of the field is checked, so an empty `itsm_link` is accepted. Populate `type`, `id`, and `link_url` to record a link that resolves to the ticket. `type` is one of `OTHER`, `SERVICE_NOW`, or `JIRA`, and defaults to `OTHER`. | {% hint style="warning" %} **The endpoint does not enforce the Required column.** It rejects the call on two conditions only: `itsm_link` is absent, or `datasource_id` does not name a Lifecycle Management datasource. `identity_id` is checked when you send it, and returns `NotFound` if it does not resolve. Every other field is stored as supplied. Send the fields marked Yes even though nothing rejects the call without them. A request that omits `target_entity_type` or `target_entity_ids` returns success and persists with no entitlements attached, one that omits the assignee fields persists with no assignee, and neither is a request an approver can act on. {% endhint %} ### Driving state transitions from external systems Veza provides four API endpoints that external ITSM systems call to report the outcome of an external access request. These are the **Mark** endpoints: #### Mark Running Signals that the external system has started processing the request. Transitions the request to **External Running**. ``` POST /api/private/lifecycle_management/access_requests/{id}:running ``` #### Mark Completed Signals that the external system successfully fulfilled the request. Transitions the request to **Completed**. ``` POST /api/private/lifecycle_management/access_requests/{id}:completed ``` #### Mark Rejected Signals that the external system rejected the request. Transitions the request to **Rejected**. ``` POST /api/private/lifecycle_management/external_access_requests/{id}:rejected ``` #### Mark Failed Signals that the request failed during external processing. Transitions the request to **Errored**. ``` POST /api/private/lifecycle_management/access_requests/{id}:failed ``` Each Mark endpoint accepts the access request `id` as a path parameter and an optional `note` in the request body to provide additional context about the state change. Note the path prefixes: Mark Running, Mark Completed, and Mark Failed are served under `access_requests`, while Mark Rejected is served under `external_access_requests`. This difference is intentional in the API surface, not a documentation error. {% hint style="info" %} **API permissions**: The Mark endpoints require the `update` permission on the `lifecycle_management_access_request` resource, are restricted to the `admin` role, and are evaluated against the root team. `CreateExternalAccessRequest` requires the `create` permission under the same role and team conditions. {% endhint %} ## Integration patterns ### Pattern 1: ServiceNow catalog item with automatic ticketing Use this pattern when you want Veza to handle the approval workflow and automatically create a ServiceNow ticket upon approval: 1. Configure a ServiceNow notification integration in Veza. 2. Create a catalog definition of type **ServiceNow** referencing the notification integration. 3. Users request access through the Veza Access Catalog. 4. Veza manages the approval workflow. 5. After approval, Veza automatically creates a ServiceNow ticket. 6. The access request is linked to the ServiceNow ticket for tracking. ### Pattern 2: External system drives fulfillment Use this pattern when the ITSM system handles both the request and fulfillment, and Veza serves as the governance layer: 1. The external system creates an access request in Veza via `CreateExternalAccessRequest`, including an ITSM link to the external ticket. 2. Veza processes the request through its approval workflow. 3. After approval, the external system picks up the request and begins fulfillment. 4. The external system calls `MarkExternalAccessRequestRunning` to indicate processing has started. 5. Upon completion, the external system calls the appropriate Mark endpoint (`Completed`, `Rejected`, or `Failed`). 6. Veza records the final state for audit and compliance purposes. ## Related documentation * [Access Requests Overview](/4yItIzMvkpAvMVFAamTf/features/access-request.md) - Complete feature overview and architecture * [Enabling Access Requests](/4yItIzMvkpAvMVFAamTf/features/access-request/enable-access-requests.md) - Initial setup and configuration guide * [Access Request Settings](/4yItIzMvkpAvMVFAamTf/features/access-request/settings.md) - Global system configuration * [Access Request Notifications](/4yItIzMvkpAvMVFAamTf/features/access-request/notifications.md) - Notification configuration for request events --- # 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.veza.com/4yItIzMvkpAvMVFAamTf/features/access-request/configure-itsm-integration.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.