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.

sequenceDiagram
    participant Admin as Platform Admin
    participant Catalog as System Catalog
    participant Project as End User Project

    Admin->>Catalog: Selects Environment Template from System Catalog
    Admin->>Catalog: Selects ServiceNow Workflow Approval Handler from System Catalog
    Admin->>Project: Shares Environment Template and Workflow Handler
    Project-->>Admin: Templates Available in End User's Project

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.

sequenceDiagram
    participant User as End User
    participant Project as Rafay Project
    participant SNOW as ServiceNow System

    User->>Project: Launches Environment Template
    Project->>SNOW: Creates Incident Ticket
    SNOW-->>User: Provides Ticket URL
    User->>SNOW: Updates Status to Approved or Canceled
    alt Approved (e.g., Resolved)
        Project->>Project: Proceeds with Environment Provisioning
        Project-->>User: Environment Status = Success
    else Denied (e.g., Canceled)
        Project-->>User: Environment Provisioning Blocked
    end

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

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.

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

This navigates to the Workflow Handlers page, which displays the default labels and annotations under General section as shown below.

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.