Configure ServiceNow Catalog Integration - Rafay Product Documentation
Getting Started with ServiceNow Workflow Approval
Overview
This guide explains how to use the ServiceNow Workflow Approval catalog to add approval-based gating to environment provisioning, update, and deletion workflows. It enables administrators to integrate ServiceNow-based incident approvals as pre-hooks in environment or resource templates to ensure provisioning proceeds only after formal approval.
The ServiceNow approval step helps enforce policy, improve governance, and track change requests using incidents in a configured ServiceNow instance.
Approval Workflow Execution
A Jupyter Notebook template is used in this guide as an example to demonstrate how ServiceNow Workflow Approval works. When the workflow handler is attached to an environment template, it automatically triggers during provisioning and creates a ServiceNow ticket (incident).
Rafay continuously monitors the incident’s status and proceeds with the provisioning only when the configured approved state (e.g., Resolved) is detected. If the incident moves to a denied state (e.g., Canceled) or times out, provisioning is blocked.
This behavior is supported for any environment template, not just notebooks. The ServiceNow workflow handler can be reused across multiple templates and projects.
Prerequisites
Before proceeding, ensure the following:
- A valid ServiceNow instance is accessible with its base URL (FQDN)
- A ServiceNow user account with required roles
- An API token and username are available for authentication
Initial Setup
This involves selecting an environment template, configuring the ServiceNow Workflow Approval handler, and sharing both with the appropriate project for end-user access.
End User Project System Catalog Platform Admin
- Selects Environment Template from System Catalog
- Selects ServiceNow Workflow Approval Handler from System Catalog
- Shares Environment Template and Workflow Handler
End User Flow
When the end user deploys the shared environment template, the attached workflow handler triggers a ServiceNow incident. Provisioning proceeds only after the incident is approved in ServiceNow.
- ServiceNow System
- Rafay Project
- End User
| Status | Action | Result |
|---|---|---|
| Approved | Launches Environment Template | Environment Status = Success |
| Denied | Creates Incident Ticket | Environment Provisioning Blocked |
Part 1: Create Jupyter Notebook Template
To begin, create a Jupyter Notebook:
- As an Org Admin, go to Template Catalog
- Select the AI/ML tab and choose the Jupyter Notebook
- Click Get Started
- Provide the following details:
- Provide a name and version name (e.g.,
1.0) - Select a project (e.g.,
defaultproject) - Click Continue
- Provide a name and version name (e.g.,
The Environment Template page appears, allowing users to provide the required inputs and deploy the notebook. Refer to the Jupyter Notebook Deployment page for detailed steps on how to deploy a notebook.
Part 2: Share the ServiceNow Workflow Approval Handler
Step 1: Select the ServiceNow Workflow Approval Template
- From the Template Catalog, select the Workflow Helpers tab, choose the ServiceNow Workflow Approval catalog, and click Get Started
- Provide the following details:
- Provide a name and version name (e.g.,
1.0) - Select a project (e.g.,
defaultproject) - Click Continue
- Provide a name and version name (e.g.,
This navigates to the Workflow Handlers page, which displays the default labels and annotations under the General section.
Step 2: Configure the ServiceNow Integration
- In the Workflow Handler page, click Configuration to provide the required input values needed to configure the ServiceNow integration and click Save
Input Variables for ServiceNow Workflow Approval Catalog
| Name | Value Type | Description |
|---|---|---|
| debug | Text | Enables verbose logging for troubleshooting purposes |
| configuration_fqdn | Text | Fully qualified domain name of the ServiceNow instance |
| configuration_api_user | Text | Username used to authenticate API requests to ServiceNow |
| configuration_api_token | Text | API key used to authenticate requests to the ServiceNow server |
| configuration_approved_state | Text | ServiceNow ticket status that indicates the request has been approved |
| configuration_denied_state | Text | ServiceNow ticket status that indicates the request has been denied |
| short_description | Text | Short summary of the resource request |
| description | Text | Detailed description of the resource request |
| assigned_to | Text | User to whom the ServiceNow ticket is assigned |
| u_notifiers | Text | Users who will be notified about the ticket status |
| priority | Text | Priority level for the ServiceNow ticket (e.g., High, Medium, Low) |
| impact | Text | Impact level for the ServiceNow ticket (e.g., High, Medium, Low) |
💡 Ticket Approval and Denial States
The ServiceNow workflow handler checks the status of the incident ticket to determine whether to proceed with resource provisioning. The following variables must be configured:
configuration_approved_state: Status value (e.g.,Resolved) that indicates approval.configuration_denied_state: Status value (e.g.,Canceled) that indicates denial. These values must match the exact status strings used in the ServiceNow instance. Incorrect or mismatched values may prevent the system from detecting resolution, causing the workflow to stall.
Once the changes are complete, users can view the workflow handlers list.
Part 3: Attach the ServiceNow Workflow Handler to an Environment Template
Navigate to Environment Templates to attach the ServiceNow Workflow Handler as a hook to the notebook environment template created in Part 1 (e.g.,
jupyter-workspace-init)Click the Edit icon for the selected environment template and go to the Hooks section
Click + Add Hook
Enter a name for the hook and select the hook type as Workflow Handler
From the list of available workflow handlers, choose the one created in Part 2 – Step 2
Provide the other details as required and click Save Changes
Click Save as Draft or Save as Active
💡 Recommended: Enable Skip On Destroy It is generally recommended to enable Skip On Destroy when configuring ServiceNow workflow handlers in self-service scenarios. Enabling this option ensures that the workflow handler is triggered only during environment provisioning and not during deletion. This prevents unnecessary approval requests or ticket creation when an environment is being removed. For specific use cases where notification or tracking during deletion is required, this option can be left disabled. In such cases, a ticket may be generated to inform stakeholders about the environment termination. This setting should be reviewed based on the expected behavior during the destroy phase of the environment lifecycle.
Part 4: Launch the Notebook Template
Navigate to Environments and launch the Jupyter Notebook created in Part 1
Provide a name and, optionally, a description
Select an active agent from the dropdown
Enter the cluster name and API Key
Click Save & Deploy
The initial status is Pending and changes to Waiting for Approval
An output is displayed with the ServiceNow link and incident_number.
Open the ServiceNow link and navigate to All → Incidents
From the incident record, select the status Resolved from the drop-down and click Update or Resolve
Once the status is updated to Resolved, the remaining provisioning steps proceed, and the environment is created successfully with the status shown as Success.
If the incident status is not changed to Resolved, the provisioning will not proceed.