> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/governance/servicenow/change-requests.md).
# 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](/flxbl/codev/governance/servicenow/gating.md), 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**).
```bash
curl -X POST \
"https:///sfp/api/integrations/servicenow/change-requests/test" \
-H "Authorization: Bearer " \
-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. |
{% hint style="warning" %}
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.
{% endhint %}
## 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:
```json
{
"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](/flxbl/codev/governance/servicenow/gating.md) for how the two relate.
## Related
* [Release gating](/flxbl/codev/governance/servicenow/gating.md) — make a release wait for its change request to be approved
* [Integrations](/flxbl/codev/integrations/overview.md) — how integrations are scoped and resolved
* [Audit trail](/flxbl/codev/settings/audit.md) — the record of every change-request decision
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.flxbl.io/flxbl/codev/governance/servicenow/change-requests.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.