Change requests

Connect ServiceNow, verify the connection, and control how change requests are created for releases.

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 two steps: connect ServiceNow, then confirm the connection creates a change request.

Connect ServiceNow

Connecting ServiceNow under Settings > Integrations.

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:

Field	What to enter
Instance URL	Your ServiceNow instance address, e.g. https://your-instance.service-now.com.
Username	The integration user, e.g. sfp.integration.
Password	The integration user's password.
Change Request Table (optional)	The table change requests are created in. Defaults to change_request.
Approval timeout — hours (optional)	How long codev waits for approval before giving up. Leave blank to wait up to 30 days. A project can override this.
Poll interval — minutes (optional)	How often codev re-checks the change request's approval state. Defaults to 15 minutes.

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.

Test your setup

Before you rely on a change request, confirm the credentials actually create one. codev has a test endpoint that opens one real change request in ServiceNow from a mock release payload and returns its number and a link — without touching any release.

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.

Response	Meaning
201	The change request was created — open the returned url to confirm it in ServiceNow.
400	The ServiceNow credentials are missing for that project, or the payload is invalid.
403	You are not an owner.
502	ServiceNow rejected or failed the request — check the instance URL, the integration user's permissions, and the change request table.

The test creates a real change request in your ServiceNow instance. After confirming it, cancel or close that test change request in ServiceNow so it doesn't sit in your CAB queue.

How change requests are created

How the change request itself is created — its timing and its CAB routing fields — is controlled with serviceNowChangeRequest in your project configuration:

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

Setting	Effect
enabled	Open a change request for every release, even for environments that are not gated on ServiceNow — the change request becomes a record of the release. A ServiceNow gate opens a change request regardless of this flag.
timeoutHours	How long codev waits for the change request to be approved when it is used as a gate. Overrides the integration's timeout for this project.
pollIntervalMinutes	How often codev re-checks the change request's state. Overrides the integration's poll interval for this project.
changeType	normal, standard, or emergency — for CAB routing.
category	The change request category.
risk	The change request risk.
assignmentGroup	The assignment group (name or sys_id) the change request is routed to.

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

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