ServiceNow Integration

Patrol’s ServiceNow integration connects your IT Service Management workflows with infrastructure automation. When a change request is approved, an incident is created, or a catalog task completes, Patrol can automatically trigger runbooks to deploy environments, update configurations, or perform operational tasks — then update ServiceNow records with the execution status.

How it works

1. The Patrol scoped app in ServiceNow sends a webhook to Patrol when a trigger condition is met (e.g., change state = “Implement”)
2. Patrol validates the request and triggers matching workflow graphs
3. Workflows can:
   • Run Patrol runbooks to orchestrate multi-environment deployments
   • Create or find customers and environments
   • Execute deployment pipelines
   • Update ServiceNow change requests, incidents, or CIs with the results

Prerequisites

• ServiceNow instance (Vancouver or later)
• Admin role (admin) to install the scoped app
• Integration user credentials (Basic auth or OAuth Bearer token) for outbound Patrol → ServiceNow actions
• A Patrol runbook or deployment template configured

Setting up the integration

1. Create the integration in Patrol

Navigate to Integrations → Add Integration → ServiceNow. Enter:

• Display Name — e.g. “Production ServiceNow”
• Instance URL — your ServiceNow instance URL (e.g. https://dev12345.service-now.com)
• Instance ID — short identifier for webhook routing (e.g. dev12345)
• Username + Password — Basic auth credentials for the ServiceNow Table API
  • OR Access Token — OAuth Bearer token
• Webhook Secret (optional) — a random string to validate webhook requests via the X-Patrol-Webhook-Secret header
• Approved change states — comma-separated state values that trigger “change approved” workflows (default: implement, -1)

2. Install the Patrol scoped app in ServiceNow

Download the Patrol ServiceNow package from the Connection tab in Patrol (or from the packages/servicenow-app directory).

Import the Update Set:

1. In ServiceNow, navigate to System Update Sets → Retrieved Update Sets
2. Click Import Update Set from XML
3. Upload the x_patrol_integration_v1.0.0.xml file
4. Open the imported update set and click Preview Update Set
5. If no conflicts appear, click Commit Update Set

What gets installed:

Artifact	Description
PatrolWebhookClient	Script Include that builds and sends webhook payloads
Patrol Change Approved	Business rule on change_request — fires when state = Implement (-1)
Patrol Incident Created	Business rule on incident — fires on all new incidents
Patrol Catalog Task Completed	Business rule on sc_task — fires when state = Closed Complete (3)
x_patrol_webhook_log	Log table for debugging outbound webhook attempts
System Properties	Three configuration properties (see below)

3. Configure ServiceNow properties

After installing the scoped app, set three system properties. Navigate to System Properties → All Properties and filter by x_patrol:

Property	Value	Where to find it
x_patrol.webhook_url	Your Patrol webhook URL	Patrol → Integration → Connection tab → Webhook URL
x_patrol.instance_id	Your instance ID	Must match the Instance ID in Patrol (e.g. dev12345)
x_patrol.webhook_secret	Shared secret (optional)	Must match the Webhook Secret in Patrol

The webhook URL follows this format:

https://api.usepatrol.dev/integrations/servicenow/webhook?instanceId=dev12345

4. Verify the installation

1. In Patrol, click Test Connection on the Connection tab
2. Create a test change request in ServiceNow and move it to the Implement state
3. Check Patrol’s integration Event Log tab for the inbound webhook event
4. In ServiceNow, check x_patrol_webhook_log.list for outbound request logs

Creating workflows in Patrol

Example: Run runbook when change approved

1. Go to Workflows → New Workflow
2. Add trigger node: ServiceNow → Change approved
3. Select your ServiceNow integration
4. Add action node: Patrol → Run runbook
5. Map fields:
   • Runbook ID: enter the UUID of your runbook
   • Target selector mode: explicit, customer, or all
   • Environment IDs: map to trigger.record.environment_ids (if you store environment IDs in a change request custom field)
6. (Optional) Add action node: ServiceNow → Update change
   • Map sys_id to trigger.sys_id
   • Map state to a completed state (e.g. 4 = “Implemented”)
   • Map work_notes to Patrol runbook execution: ${nodes.<run-runbook-node-id>.execution.id}

Available triggers

Trigger	Routing rule	Typical use case
Change approved	table === 'change_request' and state/approval in configured approved states	Deploy infrastructure when a change is ready to implement
Incident created	table === 'incident' and record was just created	Auto-remediate common incidents with runbooks
Catalog task completed	table === 'sc_task' and state is closed_complete	Provision resources after catalog fulfillment approval
Inbound webhook	Always fires (catch-all)	Custom logic for any ServiceNow table/event

Multiple triggers can fire for a single webhook if rules match (e.g., a change request webhook triggers both “change approved” and “inbound webhook” workflows).

Outbound actions

Use these workflow action nodes to update ServiceNow from Patrol:

Action	Purpose	Required fields
Update change	Update a change request	sys_id
Update incident	Update an incident	sys_id
Create record	Create a record in any table	table + record fields
Update record	Update a record in any table	sys_id, table + fields to update
Create CI	Create a CMDB Configuration Item	name, sys_class_name (optional)
Update CI	Update an existing CI	sys_id

All update actions support dynamic field mapping — map ServiceNow field names to workflow variables (e.g., state → 4, work_notes → Deployed via Patrol).

Runbook action node

The Patrol → Run runbook workflow node triggers a runbook execution. This is the primary integration point for ITSM-driven automation.

Inputs:

• Runbook ID — UUID of the runbook to execute (required)
• Target selector mode — how to select environments:
  • explicit — provide a list of environment IDs
  • customer — all environments for a customer ID
  • all — all environments in the tenant (use with caution)
• Environment IDs — for explicit mode
• Customer ID — for customer mode
• Parameters — runbook parameter overrides (nested field mapping)

Outputs:

• execution.id — the runbook execution ID
• execution.status — queued, running, succeeded, failed, or partial
• execution.runbookId — confirms which runbook was triggered

Example use: Trigger a multi-step runbook that deploys an application, runs smoke tests, and updates load balancers — all orchestrated from a ServiceNow change request approval.

Business rule conditions

The Patrol scoped app installs three async business rules. Here are the default conditions:

Rule	Table	Fires on	Condition
Patrol Change Approved	change_request	Update	State changes to Implement (-1)
Patrol Incident Created	incident	Insert	Always (all new incidents)
Patrol Catalog Task Completed	sc_task	Update	State changes to Closed Complete (3)

To customise conditions (e.g., different change states), edit the business rule in ServiceNow:

1. Navigate to System Definition → Business Rules
2. Search for the rule name (e.g. “Patrol Change Approved”)
3. Update the Filter Conditions or Script as needed

All business rules run asynchronously to avoid blocking ServiceNow transactions if Patrol is unreachable.

Testing

1. In Patrol, open your ServiceNow integration → Connection tab
2. Click Test Connection — this validates credentials and instance URL
3. Create a test change request in ServiceNow and move it to the “Implement” state
4. Check Patrol’s integration Event Log tab for the inbound webhook event
5. Check Workflows → Executions for triggered workflow runs
6. If workflows didn’t trigger, verify:
   • The integration is Enabled
   • The business rules are Active in ServiceNow (check sys_script.list)
   • The x_patrol.webhook_url and x_patrol.instance_id properties are set correctly
   • The webhook secret matches (if used)
   • The trigger node’s integration ID matches your ServiceNow integration

Security notes

• Store webhook secrets securely — use a password manager to generate long random values
• The x_patrol.webhook_secret property is stored as a password type (encrypted at rest) in ServiceNow
• Use ServiceNow MID Server or IP allowlisting if Patrol is behind a firewall
• Patrol validates the X-Patrol-Webhook-Secret header using timing-safe comparison to prevent timing attacks
• ServiceNow credentials are encrypted at rest in Patrol’s database
• The scoped app uses the x_patrol namespace and does not access unrelated ServiceNow tables
• Business rules run asynchronously — ServiceNow transactions are not blocked by Patrol downtime

Troubleshooting

Webhook returns 400 “Integration not found”

• Verify x_patrol.instance_id in ServiceNow matches the Instance ID in Patrol
• Check that the ServiceNow integration is not archived

Webhook returns 401 “Invalid webhook secret”

• Ensure x_patrol.webhook_secret in ServiceNow matches Patrol’s stored secret
• If you don’t want to use webhook auth, leave both the ServiceNow property and Patrol field empty

Business rules not firing

• Verify the business rules are Active: navigate to sys_script.list and filter by name starts with “Patrol”
• Check that the state condition matches (e.g., state = -1 for change_request, state = 3 for sc_task)
• Check ServiceNow system logs for errors containing “Patrol Integration”

Workflows don’t trigger

• Check the integration’s Event Log — if events are logged but workflows didn’t run, the trigger conditions may not match
• For “Change approved”, verify the change request’s state or approval field is in the configured approved states list
• Ensure at least one workflow has a matching ServiceNow trigger node with the correct integration selected

No entries in x_patrol_webhook_log

• Verify the log table exists: navigate to x_patrol_webhook_log.list
• If the table is missing, the scoped app may not have been fully committed

Test connection fails

• Verify instance URL is correct and accessible
• Check username/password or access token permissions — the user needs read access to the sys_properties table

MID Server required

• If your ServiceNow instance cannot make outbound REST calls directly (firewall restrictions), configure a MID Server for outbound web service calls

Legacy manual setup (Flow Designer)

If you cannot install the Patrol scoped app (e.g., due to change control policies), you can manually configure ServiceNow Flow Designer flows.

Create a Flow

1. Go to Flow Designer → New Flow
2. Choose a trigger:
   • Change Management → When a change_request is updated
   • Incident Management → When an incident is created
   • Service Catalog → When a catalog task state changes
3. Add conditions to filter the trigger (e.g., “State is Implement” for change requests)

Add a REST Message action

1. Add action: REST Message
2. Configure:
   • HTTP Method: POST
   • Endpoint: copy the Webhook URL from Patrol’s integration Connection tab
   • Headers: add X-Patrol-Webhook-Secret with your webhook secret (if configured)
   • Request Body: JSON with required fields:

{
  "sys_id": "${trigger.sys_id}",
  "table": "change_request",
  "number": "${trigger.number}",
  "eventType": "change_approved",
  "short_description": "${trigger.short_description}",
  "state": "${trigger.state}"
}

Required fields:

• sys_id — the record’s sys_id
• table — the ServiceNow table name (e.g. change_request, incident, sc_task)

Optional but recommended:

• eventType — descriptive event type (e.g. change_approved, incident_created)
• number — the record number (CHG0001234, INC0005678, etc.)
• Any record fields you want available in Patrol workflows (e.g. short_description, priority, assigned_to)

Save and activate the Flow.