ServiceNow change requests

codev can open a ServiceNow change request for a release and write the changed packages into it — each package, its previous and new version, and the linked work items — so the change request records exactly what is being deployed. This is the foundation for release gating, but you can also use it on its own, purely to record releases in ServiceNow.

Setting it up has three steps: connect ServiceNow, configure what the change request contains, then confirm it actually creates one.

Connect ServiceNow

Go to Settings > Organization > Integrations and add the ServiceNow provider. Only organization owners can manage integrations.

In ServiceNow, first create or choose a dedicated integration user with change-management write access (for example the sn_change_write role), and set a password for it. Then fill in the form:

Set Availability to make the connection available to all projects or to a single project, and save. The credentials are stored encrypted; codev talks to ServiceNow on your behalf using them.

This form is only the connection. What the change request contains, and how long codev waits for it, is set separately — see below.

Configure change requests

Once ServiceNow is connected, select Configure change request on the integration page. The dialog holds everything about the change request itself, so you do not have to hand-write project configuration to get started.

Gate behaviour

The top section controls where the change request is created and how long codev waits for CAB.

Change request fields

These are the values written to the change request:

Any field can take a merge field — a release, environment, repository or current-time value resolved at gate time. Pick one from the list on the right to insert it, or type {{ to search.

Merge fields work inside surrounding text, so Release {{release.candidate}} to {{environment.targetsCsv}} reaches ServiceNow as Release core:RC-2026-08-12 to uat, prod. Use Preview payload to see every field resolved against a sample release before you save.

Use Additional change request parameters for your instance's own u_* columns. They are written alongside the standard fields, and take merge fields the same way.

Preview the payload and send a test

Select Preview payload to replace the merge field list with the request codev will send — the merge fields resolved against a sample release, so you can confirm the shape before saving. Note that the risk shows as its stored value ("3" for Moderate).

Send test change request creates one real change request in ServiceNow from that payload, without touching any release, and returns its number and a link.

Test from the API

The same test is available as an endpoint, for scripting a setup check. Send a POST to integrations/servicenow/change-requests/test on your codev server. It requires the owner role; authenticate with an application token (create one under Settings > Organization > Application Tokens).

curl -X POST \
  "https://<your-codev-server>/sfp/api/integrations/servicenow/change-requests/test" \
  -H "Authorization: Bearer <application-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryIdentifier": "your-org/your-repo",
    "releaseCandidate": "core:SNOW-INTEGRATION-TEST",
    "environments": ["uat"],
    "fields": { "category": "software", "risk": "3" }
  }'

Only repositoryIdentifier is required — it selects which project's ServiceNow connection to use. The rest are optional: releaseCandidate and environments populate the mock payload, shortDescription / description override the text, fields adds any extra ServiceNow change_request fields, and correlationId reuses an existing test change request instead of creating a new one.

A successful call returns the created change request — its number, state, approval, and a url you can open in ServiceNow — along with the correlationId and the table it was created in. Stored credentials are never returned.

How change requests are created

Everything in the dialog is stored as serviceNowChangeRequest in your project configuration, so you can also set it there directly, review it in a pull request, or override the integration's defaults per project:

{
  "serviceNowChangeRequest": {
    "enabled": true,
    "timeoutHours": 24,
    "pollIntervalMinutes": 5,
    "changeType": "normal",
    "category": "Software",
    "risk": "3",
    "assignmentGroup": "Salesforce CAB"
  }
}

If you omit timeoutHours or pollIntervalMinutes here, codev uses the values from the integration (up to 30 days, checked every 15 minutes, by default).

Field templates

The merge fields you insert in the dialog are stored under fieldTemplate, which also accepts them written by hand. A value is either a plain string, or a directive:

{
  "serviceNowChangeRequest": {
    "fieldTemplate": {
      "u_release": { "$path": "release.candidate" },
      "u_product": { "$format": "Salesforce {{release.candidate}} to {{environment.targetsCsv}}" },
      "start_date": { "$datetime": { "$path": "now.dateTime" } }
    }
  }
}

Merge-field catalogue

The rail in the dialog lists these, and owners can retrieve the authoritative catalogue from GET /integrations/servicenow/field-catalog. Each entry carries the path, type, description and an example.

ServiceNow fields are flat, so use the scalar forms — release.candidatesCsv, environment.targetsCsv, environment.gateSummariesCsv, workItems.csv, packageChanges.count — where the underlying value is an array.

Glide date and time

$datetime accepts an ISO-8601 timestamp with Z or a numeric offset. codev converts the instant to UTC and emits yyyy-MM-dd HH:mm:ss, so 2026-10-08T14:20:00-04:00 is written as 2026-10-08 18:20:00. Naive or invalid timestamps are rejected.

$date emits yyyy-MM-dd. It accepts a date-only value or an offset-aware ISO timestamp, from which codev derives the UTC calendar date.

Without one of the two, a raw ISO timestamp is rejected or silently dropped.

Current time

now.dateTime and now.date resolve to the time the change request is created.

To start the change window when the change request is opened, set Planned start to {{now.dateTime}}. This is stored as:

"start_date": { "$datetime": { "$path": "now.dateTime" } }

To start it today at a fixed time — say 09:00 UTC — write the time around {{now.date}}:

"start_date": { "$datetime": { "$format": "{{now.date}}T09:00:00Z" } }

now.* is resolved once per change request. Re-requesting a release while its change request is still waiting for a decision keeps the original start_date; after a rejection or timeout, the next request moves it to the current time.

Creating a change request is separate from making a release wait for its approval — see Release gating for how the two relate.

Related

• Release gating — make a release wait for its change request to be approved
• Integrations — how integrations are scoped and resolved
• Audit trail — the record of every change-request decision