ServiceNow PDI Developer Environment Setup¶

This guide walks through getting a free ServiceNow Personal Developer Instance (PDI) and configuring it for the Azure Monitor integration. If you don't want to use a live SNOW instance at all, skip to Local Mock (No SNOW account required).

What is a PDI?¶

A ServiceNow PDI is a free, full-featured ServiceNow instance available to any developer who registers at developer.servicenow.com. It includes ITSM, ITOM, Table API, Integration Hub, Flow Designer — everything needed to test this integration.

PDI facts: - Completely free — no credit card, no trial expiry - Same platform as enterprise ServiceNow — full Table API, Business Rules, CMDB - Hibernates after ~10 days of inactivity (you get email warnings before it sleeps) - Wakes back up in ~5 minutes when you log in; or request a new one if it expired - Outbound email is disabled by ServiceNow (not relevant for this integration) - Do NOT use ServiceNow Learning Lab instances — those are temporary and get wiped

Step 1: Get a PDI¶

Go to developer.servicenow.com
Click Sign In → Create Account (free)
After login, click Start Building or go to My Instance in the header
Click Request Instance
Select your ServiceNow release — Washington DC (or later) recommended for this integration
Wait 2–5 minutes for provisioning
Copy your instance URL (e.g., https://dev123456.service-now.com) and note your admin credentials

Open your instance URL in a browser and log in as admin
On first login you may see a Setup Wizard — you can dismiss it
Key navigation for this integration:

Where to go	How to get there
Incidents list	Service Desk → Incidents (or search `incident.list` in the nav filter)
Users	User Administration → Users
Business Rules	System Definition → Business Rules
REST API Explorer	System Web Services → REST API Explorer
Application Registry	System OAuth → Application Registry

Verify the Table API works from your browser:
```
https://dev123456.service-now.com/api/now/table/incident?sysparm_limit=5
```
You should see a JSON response with sample incidents (browser will prompt for credentials).

Step 3: Wake a Hibernated Instance¶

If your PDI hibernated:

Go to developer.servicenow.com → My Instance
Click Wake Up — the instance will be available in ~5 minutes
If the instance expired, click Request Instance to get a fresh one
Note: a fresh instance loses any customizations (Business Rules, users) — re-run New-SnowPdiSetup.ps1 to restore them

Step 4: Automated Setup (Recommended)¶

Run New-SnowPdiSetup.ps1 to create the integration service account and verify the API:

.\deploy\scripts\New-SnowPdiSetup.ps1 `
  -SnowInstanceUrl https://dev123456.service-now.com `
  -AdminUsername admin

The script will: - Create the azure_monitor_svc service account - Assign itil + rest_service roles - Create and close a test incident - Optionally create the Business Rule (if you provide -CloseLogicAppWebhookUrl)

Step 5: Manual Setup (Alternative)¶

Create the Integration User¶

Navigate to User Administration → Users
Click New
Fill in:
User ID: azure_monitor_svc
First/Last name: Azure Monitor Integration
Password: Choose a strong password (this goes in Key Vault)
Active: Checked
Save the record

Assign Roles¶

On the new user record: 1. Scroll to the Roles related list 2. Click Edit 3. Add: itil, rest_service 4. Click Save

Step 6: Configure the Business Rule (Bi-Directional Close)¶

The Business Rule fires the Close Logic App when an Azure Monitor-sourced incident is resolved.

Get the Close Logic App Webhook URL¶

# After deploying the Close Logic App
(Get-AzLogicAppTriggerCallbackUrl -ResourceGroupName rg-azure-monitor-itsm `
  -Name 'Azure-Monitor-Close-ITSM-HTTP-API' `
  -TriggerName 'When_a_HTTP_request_is_received').Value

Create the Business Rule¶

In SNOW, navigate to System Definition → Business Rules
Click New
Configure:
Name: Azure Monitor Close Alert on Ticket Complete
Table: Incident [incident]
Advanced: Checked
When: After
Insert: Unchecked, Update: Checked
In the Filter Conditions tab, add:
State | is | Resolved
In the Advanced tab, paste the script from src/servicenow/snow-automation-rule-script.js
Replace <CLOSE-LOGIC-APP-WEBHOOK-URL> with the URL from the previous step
Save

Step 7: Verify in the SNOW UI¶

After running Test-Integration.ps1, confirm in the PDI:

Navigate to Service Desk → Incidents
Search for the test incident — short description will contain "TestAlertRule-Integration"
Open the record and verify:
Correlation ID field = the Azure Monitor alertId (starts with /subscriptions/)
Impact, Urgency, Priority match the Sev2 → Moderate mapping
State = Resolved (if the close was also tested)

To see incoming REST API calls in the PDI: 1. Go to System Log → All (search syslog.list in the nav filter) 2. Filter Source = REST — all inbound Table API calls from the Logic App appear here

Step 8: Test the Integration¶

# Run the end-to-end test
.\deploy\scripts\Test-Integration.ps1 -ResourceGroupName rg-azure-monitor-itsm

This will: 1. POST a sample metric alert to the Alert Logic App 2. Poll SNOW for the created incident (correlation_id matching the test alertId) 3. Report the SNOW incident number on success

SNOW Table API Reference¶

Base URL: https://{instance}.service-now.com/api/now/table/{tableName}

Operation	Method	Endpoint	Notes
Create incident	POST	`/api/now/table/incident`	Returns `sys_id`
Update incident	PATCH	`/api/now/table/incident/{sys_id}`
Query by correlation_id	GET	`/api/now/table/incident?sysparm_query=correlation_id=...`
Lookup CI	GET	`/api/now/table/cmdb_ci_computer?sysparm_query=name=...`	Used for CI field

Correlation ID Pattern¶

The Azure Monitor alertId is stored in SNOW's correlation_id field:

/subscriptions/{subscriptionId}/providers/Microsoft.AlertsManagement/alerts/{alertGuid}

The Close Logic App uses correlation_id to find and close the right Azure Monitor alert.
The Business Rule identifies Azure Monitor-sourced tickets by checking if correlation_id starts with /subscriptions/.

REST API Explorer (PDI Built-In)¶

The PDI includes a built-in REST API Explorer — useful for manually testing API calls before the Logic App is wired up:

In your PDI, navigate to System Web Services → REST API Explorer
Select Table API → POST /now/table/{tableName}
Set tableName = incident
Paste a sample body from samples/snow-responses/incident-created.json
Click Send — you'll see the full request/response with headers

This lets you verify your service account has the correct permissions before deploying the Logic Apps.

Local Mock (No SNOW Account Required)¶

If you don't have a PDI yet (or want fully offline development), use the included Docker mock:

cd dev/docker
docker-compose up

This starts json-server on http://localhost:3000 with routes that mirror the ServiceNow Table API:

SNOW Table API	Mock equivalent
`POST /api/now/table/incident`	`POST http://localhost:3000/api/now/table/incident`
`GET /api/now/table/incident?sysparm_query=...`	`GET http://localhost:3000/api/now/table/incident`
`PATCH /api/now/table/incident/{id}`	`PATCH http://localhost:3000/api/now/table/incident/{id}`

Pre-seeded data is in dev/docker/mock-snow-db.json — add/edit records there.

To test with the mock instead of SNOW: 1. Set ItsmApiIntegrationCode in Key Vault to your machine's public IP + port 3000 2. Set ItsmApiUserName / ItsmApiSecret to any values (json-server doesn't check auth) 3. Run the Logic App — it will POST to the mock endpoint 4. Verify the incident was recorded: curl http://localhost:3000/incident

Note: The mock is for local Logic App payload development only. It does not send webhooks back to the Close Logic App (no Business Rule equivalent). Use a real PDI for full bi-directional testing.

Dev Container¶

Open this repo in VS Code and click Reopen in Container — the Dev Container in dev/.devcontainer/ includes:

Azure CLI + Bicep extension
Terraform ≥ 1.5
PowerShell 7 + Az module (auto-installed on container create)
GitHub CLI
VS Code extensions: Bicep, Terraform, PowerShell, Logic Apps, REST Client

Port 3000 is automatically forwarded from the container so docker-compose up in dev/docker/ works without any extra configuration.