DevOps API
- UpdatedJul 31, 2025
- 68 minutes to read
- Zurich
- API reference
The DevOps API provides endpoints that enable the interaction with external DevOps tools.
This REST API enables integrators to:
- Retrieve the available DevOps tools associated with an instance.
- Retrieve the schema object for a code resource, plan, or orchestration resource.
- Check if an orchestration task is under change control and check its change control status.
- Create callbacks to associate with task executions under change control.
- Send various event payloads, which are transformed into normalized objects and stored as code, orchestration, and plan objects.
- Search a commit, branch, or repository using encoded queries and specific search/sort criteria.
- Register artifact versions and packages along with their associated pipeline execution and commits.
- Create and manage onboarding application and tool events.
For additional information, see DevOps Config.
Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties.
DevOps - GET /devops/code/schema
Returns the schema object for a specified code resource: commit, repository, or branch.
Once you have the required schema object, use it to create the request body for your corresponding POST call; POST /code/commit, POST /code/repository, or POST /code/branch.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/code/schema
Default URL: /api/sn_devops/devops/code/schema
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| resource | Required. Type of resource schema to return. Valid values (not case-sensitive):
Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Request completed successfully. |
| 401 | Invalid or missing authentication. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| branch | Description of the branch in which the code commit was made.
Data type: Object |
| branch.name | Name of the branch in which the code commit was made.
Data type: String |
| branch.path | Relative path of the branch.
Data type: String |
| commits | Description of the commits. Data type: Array of Objects |
| commits.committedDate | Date/time on which the code was committed in source DevOps tool.
Data type: String Format: ISO 8601 with time zone offset For example: 1970-01-01T08:15:30-05:00 |
| commits.committer | Description of the person/entity that requested the commit.
Data type: Object |
| commits.committer.email | Email address of the person that requested the
commit.
Data type: String |
| commits.details | Details of the commit.
Note: Including details in a commit is not mandatory. This endpoint returns an empty array for details if they are not included in the commit.
Data type: Array of Objects |
| commits.details.action | Action that was performed on the file.
Data type: String |
| commits.details.additions | Total number of additions in the
file.
Data type: Number |
| commits.details.changes | Total number of changes that were
made.
Data type: Number |
| commits.details.deletions | Total number of deletions in the
file.
Data type: Number |
| commits.details.file | Path of the file that was modified relative to the branch.
Data type: String |
| commits.details.totalChanges | Total number of additions and
deletions.
Data type: Number |
| commits.id | Source platform identifier or the commit SHA. Data type: String |
| commits.url | URL of the commit, such as
"https://github.com/mycompany/mobileplatform/commit/3fa85f6457174562b3fc2c963f66afa6". Data type: String |
| name | Name of the branch or repository, such as "Master" or "Platform-Mobile". Data type: String |
| path | Relative path of the branch.
Data type: String |
| repository | Description of the repository in which the commit was made.
Data type: Object |
| repository.name | Name of the repository.
Data type: String |
| repository.url | URL of the repository in the source DevOps tool.
Data type: String |
| url | URL of the repository, such as
"https://github.com/mycompany/mobileplatform". Data type: String |
Example: Sample cURL request for resource=branch
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=branch" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"name": "Master",
"path": "refs/heads/master",
"repository": {
"name": "Platform-Mobile",
"url": "https://github.com/mycompany/mobileplatform"
}
}
}Example: Sample cURL request for resource=commit
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=commit" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"repository": {
"name": "Platform-Mobile",
"url": "https://github.com/mycompany/mobileplatform"
},
"branch": {
"name": "refs/heads/master"
},
"commits": [
{
"committer": {
"email": "name@email.com"
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"url": "https://github.com/mycompany/mobileplatform/commit/3fa85f6457174562b3fc2c963f66afa6",
"committedDate": "2022-01-01T08:15:30-05:00",
"details": [
{
"action": "edit",
"changes": "",
"file": "/azure-pipelines.yml",
"additions": 1,
"deletions": 0,
"totalChanges": 1
}
]
}
]
}
}Example: Sample cURL request for resource=repository
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=repository" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"name": "Platform-Mobile",
"url": "https://github.com/mycompany/mobileplatform"
}
}DevOps - GET /devops/onboarding/status
Returns the current status of the specified onboarding event which is processed or being processed asynchronously by the DevOps service.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/onboarding/status
Default URL: /api/sn_devops/devops/onboarding/status
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| id | Unique identifier of the onboarding event whose status to return. This value is
provided in the return results of the endpoint that invoked the event request, such
as /devops/onboarding/app or
/devops/onboarding/tool. Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 202 | Pending - The onboarding request has been created and the DevOps service is processing the request. |
| 207 | Partial Success - The onboarding request has been created and the DevOps service will process the request. |
| 400 | Failed - The onboarding event failed. |
| 404 | Failed - The endpoint failed to find any request matching the specified event ID. |
Response body parameters
| Name | Description |
|---|---|
| result | Results of the onboarding request. Data type:
Object |
| result.code | HTTP status code. Data type: String |
| result.importRequestsSysIds | List of import requests that have been created as a part on the onboarding
request. Data type: Array of Strings |
| result.messageDetails | Details about the onboarding event progress. Data type:
Object |
| result.messageDetails.apps | Defines the apps to create within the associated ServiceNow instance. Data type: Array of Objects |
| result.messageDetails.apps.appId | Sys_id of the application that was generated when the application was onboarded. Data type: String Table: Apps [sn_devops_app] |
| result.messageDetails.apps.message | Message that describes the status of the application onboarding. Data type: String |
| result.messageDetails.apps.name | Name of the application being onboarded. Data type: String |
| result.messageDetails.apps.status | Current status of the application onboarding. Possible values:
Data type: String |
| result.messageDetails.pipelines | List of pipelines associated with the onboarding event and their corresponding details. Data type: Array of Objects |
| result.messageDetails.pipelines.changeStepAssociation | Array of objects that describe any change steps that are associated with the onboarding. Data type: Array of Objects |
| result.messageDetails.pipelines.changeStepAssociation.changeStepName | Name of the change step. Data type: String |
| result.messageDetails.pipelines.changeStepAssociation.status | Status of change step association to the pipeline. Possible values:
Data type: String |
| result.messageDetails.pipelines.changeStepAssociation.summary | Summary of the status of the change step association. Data type: String |
| result.messageDetails.pipelines.errors | List of errors detected when associating the pipeline. Data type: Array |
| result.messageDetails.pipelines.message | Message that describes the status of the pipeline association. Data type: String |
| result.messageDetails.pipelines.name | Name of the pipeline. Data type: String |
| result.messageDetails.pipelines.status | Status of the pipeline association. Data type: String |
| result.messageDetails.plans | List of plans associated with the onboarding event and their corresponding details. Data type: Array of Objects |
| result.messageDetails.plans.errors | List of errors detected when associating the plan. Data type: Array |
| result.messageDetails.plans.message | Message that describes the status of the pipeline association. Data type: String |
| result.messageDetails.plans.name | Name of the plan. Data type: String |
| result.messageDetails.plans.status | Status of the plan association. Data type: String |
| result.messageDetails.repositories | List of repositories associated with the onboarding event and their corresponding details. Data type: Array of Objects |
| result.messageDetails.repositories.configureStatus | Details of the webhook configuration status for the repository. Data type: Object |
| result.messageDetails.repositories.configureStatus.message | Message that describes the current webhook configuration status. Data type: String |
| result.messageDetails.repositories.configureStatus.status | Status of the webhook configuration. Data type: String |
| result.messageDetails.repositories.message | Message that describes the current repository association status. Data type: String |
| result.messageDetails.repositories.name | Name of the repository. Data type: String |
| result.messageDetails.repositories.status | Status of the repository association. Data type: String |
| result.messageDetails.status | Status of the onboarding request. Possible values:
Data type: String |
| result.messageDetails.toolResponse | List of tools to onboard within the associated ServiceNow instance. Data type: Array of Objects |
| result.messageDetails.toolResponse.configureStatus | Configuration status of the tool. In case of success, it returns the status and message. In case of error, it returns the status and
error. Data type: Object |
| result.messageDetails.toolResponse.configureStatus.error | Errors detected during tool configuration. Data type: String |
| result.messageDetails.toolResponse.configureStatus.message | Message that describes the successful status of the tool configuration. Data type: String |
| result.messageDetails.toolResponse.configureStatus.status | Status of the tool configuration. Data type: String |
| result.messageDetails.toolResponse.connectStatus | Connection status of the tool. In case of success, it returns the status and message. In case of error, it returns the status and
error. Data type: Object |
| result.messageDetails.toolResponse.connectStatus.error | Errors detected during tool connection. Data type: String |
| result.messageDetails.toolResponse.connectStatus.message | Message that describes the successful status of the tool connection. Data type: String |
| result.messageDetails.toolResponse.connectStatus.status | Status of the tool connection. Data type: String |
| result.messageDetails.toolResponse.createStatus | Creation status of the tool. In case of success, it returns the status and message. In case of error, it returns the status and
error. Data type: Object |
| result.messageDetails.toolResponse.createStatus.error | Errors detected during tool creation. Data type: String |
| result.messageDetails.toolResponse.createStatus.message | Message that describes the successful status of the tool creation. Data type: String |
| result.messageDetails.toolResponse.createStatus.status | Status of the tool creation. Data type: String |
| result.messageDetails.toolResponse.discoveryStatus | Discovery status of the tool. In case of success, it returns the status and message. In case of error, it returns the status and
error. Data type: Object |
| result.messageDetails.toolResponse.discoveryStatus.error | Errors detected during tool discovery. Data type: String |
| result.messageDetails.toolResponse.discoveryStatus.imports | List of entities that were discovered. Data type: Array of Objects |
| result.messageDetails.toolResponse.discoveryStatus.imports.details | Details that describe the import performed. Data type: String |
| result.messageDetails.toolResponse.discoveryStatus.imports.id | Sys_id of the import request. Data type: String Table: sn_devops_m2m_inbound_event_import_request |
| result.messageDetails.toolResponse.discoveryStatus.imports.status | Status of the import. Data type: String |
| result.messageDetails.toolResponse.discoveryStatus.message | Message that describes the status of the tool discovery. Data type: String |
| result.messageDetails.toolResponse.discoveryStatus.status | Status of the tool discovery. Data type: String |
| result.messageDetails.toolResponse.name | Name of the tool being onboarded. Data type: String |
| result.messageDetails.toolResponse.status | Status of the tool onboarding. Data type: String |
| result.messageDetails.toolResponse.type | Type of tool, such as Jira or Jenkins. Data type: String |
| result.onboardingRequestID | Unique identifier of the onboarding request. Use this value when calling the
/devops/onboarding/status endpoint to obtain the status of the
associated tool onboarding process. Data type: String |
| result.status | Status of the onboarding request. Possible values:
Data type: String |
Example: cURL request
The following example shows the status request of a tool onboarding.
curl -X GET "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/status?id=IBE0001603" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \{
"result": {
"code": "207",
"onboardingRequestID": "IBE0001603",
"status": "partial-success",
"messageDetails": {
"status": "Partial Success",
"toolResponse": [
{
"name": "Primary Azure",
"type": "Azure DevOps",
"status": "Partial Success",
"createStatus": {
"status": "Success",
"message": "Created successfully"
},
"connectStatus": {
"status": "Failed",
"error": "Method failed: (/testFirst/_apis/work/boards) with code: 401 - Invalid username/password combo"
}
},
{
"name": "Primary Jenkins",
"type": "Jenkins",
"status": "Success",
"createStatus": {
"status": "Success",
"message": "Created successfully"
},
"connectStatus": {
"status": "Success",
"message": "Connected successfully"
},
"discoveryStatus": {
"status": "Success",
"message": "Discovered successfully",
"imports": [
{
"status": "completed",
"id": "2a4d216bdb2d2450fe4fd6a75e9619c3",
"details": "Discovered 1 new job(s) and 3 new pipeline(s)\n"
}
]
}
},
{
"name": "Primary GitHub",
"type": "GitHub",
"status": "Success",
"createStatus": {
"status": "Success",
"message": "Created successfully"
},
"connectStatus": {
"status": "Success",
"message": "Connected successfully"
},
"discoveryStatus": {
"status": "Success",
"message": "Discovered successfully",
"imports": [
{
"status": "completed",
"id": "7f4d616bdb2d2450fe4fd6a75e9619c2",
"details": "Discovered 5 new repositories. "
}
]
}
},
{
"name": "Primary Bitbucket",
"type": "BitBucket",
"status": "Success",
"createStatus": {
"status": "Success",
"message": "Created successfully"
},
"connectStatus": {
"status": "Success",
"message": "Connected successfully"
},
"discoveryStatus": {
"status": "Success",
"message": "Discovered successfully",
"imports": [
{
"status": "completed",
"id": "815da16bdb2d2450fe4fd6a75e9619d0",
"details": "Discovered 11 new repositories. "
}
]
}
},
{
"name": "Primary Gitlab",
"type": "GitLab",
"status": "Partial Success",
"createStatus": {
"status": "Success",
"message": "Created successfully"
},
"connectStatus": {
"status": "Failed",
"error": "The current operation ended in state: ERROR"
}
}
],
"importRequestsSysIds": [
"2a4d216bdb2d2450fe4fd6a75e9619c3",
"7f4d616bdb2d2450fe4fd6a75e9619c2",
"815da16bdb2d2450fe4fd6a75e9619d0"
]
}
}
}Example: cURL request
The following example shows the status request of an application onboarding.
curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/status?onboardingRequestID=IBE0001604" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \{
"result": {
"code": "207",
"onboardingRequestID": "IBE0001604",
"status": "partial-success",
"messageDetails": {
"status": "Partial Success",
"apps": [
{
"name": "Bike Rentals Service",
"status": "Success",
"appId": "c7fd696bdb2d2450fe4fd6a75e961993",
"message": "App by name 'Bike Rentals Service' has been successfully created"
}
],
"pipelines": [
{
"name": "Bike Rentals",
"status": "Success",
"message": "Successfully associated with app 'Bike Rentals Service'",
"changeStepAssociation": [
{
"status": "Success",
"changeStepName": "Prod",
"summary": "Change step with name 'Prod' has been created"
}
]
}
],
"repositories": [
{
"name": "nowdevops01/BikeRentals",
"status": "Partial Success",
"message": "Successfully associated with app 'Bike Rentals Service'",
"configureStatus": {
"status": "Failed",
"message": "Webhook configuration failed due to empty credentials for repository by name nowdevops01/BikeRentals in tool Primary GitHub"
}
}
],
"plans": [
{
"status": "Failed",
"name": "testFirst",
"errors": [
"Plan by name 'testFirst' does not exist in tool Primary Azure"
]
}
]
}
}
}DevOps - GET /devops/orchestration/changeControl
Checks if the orchestration task is under change control.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/changeControl
Default URL: /api/sn_devops/devops/orchestration/changeControl
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| orchestrationTaskName | Name of the orchestration task to check. Data type: String |
| testConnection | Flag that indicates whether to test the end-to-end connection between the instance and the DevOps tool. Valid values:
Data type: Boolean Default: false |
| toolId | Required. Sys_id of the orchestration tool. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| toolType | Type of tool. Valid values: jenkins Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Invalid or missing authentication. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| changeControl | Flag that indicates whether the orchestration task is under change control. Possible values:
Data type: Boolean |
Example: Under change control and using API v2
curl -X GET "https://instance.servicenow.com/api/sn_devops/v2/devops/orchestration/changeControl?toolId=1c219f7e8708f1508ca933383cbb3543&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins"
-H "accept: application/json"\
-H "Authorization: sn_devops.DevOpsToken 1c219f7e8708f1508ca933383cbb3543:FtN13dfDuahYEtdfDvhHorh0QPp9na3u"Response body.
{
"result": {
"changeControl": true,
"status": "Success"
}
}Example: Not under change control and using API v1
curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins"
-H "accept: application/json"\
-u "username":"password"Response body.
{
"result": {
"changeControl": false
}
}DevOps - GET /devops/orchestration/changeInfo
Retrieves change request details for a specified orchestration pipeline execution.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/changeInfo
Default URL: /api/sn_devops/devops/orchestration/changeInfo
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| branchName | Name of the branch associated with the orchestration task. Note: You should provide this parameter when referencing multi-branch pipelines or the response may include incorrect change details. Data type: String |
| buildNumber | Required. Pipeline build number within the orchestration tool. Data type: String |
| pipelineName | Optional for Jenkins Freestyle or Maven projects, required for all others.
Orchestration pipeline name. Data type: String |
| projectName | Required for Jenkins Freestyle or Maven projects, optional for all others.
Orchestration tool project name. Data type: String |
| stageName | Optional for Jenkins Freestyle or Maven projects, required for all others. Orchestration stage name. Data type: String Maximum length: 160 |
| toolId | Required. Sys_id of the orchestration tool. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 404 | Not found. The requested item wasn't found. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| changeFound | Flag that indicates whether the change request was located. Possible values:
Data type: Boolean |
| number | Change request number. Data type: String |
| phase | Current phase. Data type: String |
| phase_state | State of the current phase. Data type: String |
| priority | Priority of the change request. Priority is based on the impact and urgency of the request. It identifies how quickly the service desk should address the request. Possible values:
Data type: String |
| risk | Level of risk for the change. Possible values:
Data type: String |
| state | State of the change request. Possible values:
Data type: String Default: New |
| sys_id | Sys_id of the change request. Data type: String |
| type | Type of change request. Possible values:
Data type: String |
| url | URL of the change request within the associated ServiceNow instance. Data type: String |
| changeAssignmentGroup | Assignment group of the change request. Data type: String |
| changeApprovers | List of approvers with whom the change is pending for approval. Data type: String |
| plannedStartDate | Planned start date and time of the change. Data type: String |
| plannedEndDate | Planned end date and time of the change. Data type: String |
Example: cURL request
curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeInfo?toolId=1487f457db642810765555535e9619d3&pipelineName=Automation/apps HR/family release&stageName=deployfamilyrelease&buildNumber=1639"
-H "accept: application/json"\
-u "username":"password"{
"result": {
"changeFound": true,
"sys_id": "ee89341bdb642810765555535e96196e",
"number": "CHG0030001",
"type": "normal",
"state": "0",
"phase": "requested",
"phase_state": "open",
"priority": "4",
"risk": "4",
"url": "https://instance.servicenow.com/change_request.do?sys_id=ee89341bdb642810765555535e96196e",
"changeAssignmentGroup": "Change Management",
"changeApprovers": "Ron Kettering, Christen Mitchell, Howard Johnson, Luke Wilson",
"plannedStartDate": "2023-02-05 08:00:00",
"plannedEndDate": "2024-02-05 08:00:00"
}
}DevOps - GET /devops/orchestration/schema
Returns the schema object for a specified orchestration resource.
Once you have the required schema object, use it to create the request body for your corresponding POST call; /orchestration/orchestrationTask or /orchestration/taskExecution.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/schema
Default URL: /api/sn_devops/devops/orchestration/schema
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| resource | Type of resource schema to return. Valid values (not case-sensitive):
Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Request completed successfully. |
| 401 | Invalid or missing authentication. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| callbackURL | URL of the callback. Data type: String |
| endDateTime | Date/time that the task execution ended.
Data type: String |
| name | Name of the orchestration task. Data type: String |
| number | Task
execution number. Same as an incident number.
Data type: String |
| orchestrationTaskDetails | Description of the orchestration task.
Data type: Object |
| orchestrationTaskDetails.message | Free-form text
message.
Data type: String |
| orchestrationTaskDetails.name | Name of the orchestration task.
Data type: String |
| orchestrationTaskDetails.triggerType | The way the orchestration task was started.
Data type: String |
| orchestrationTaskDetails.url | URL of the associated orchestration tool's orchestration task.
Data type: String |
| orchestrationTaskURL | URL of the orchestration task.
Data type: String |
| result | Execution result of the task execution.
Valid values:
Data type: String |
| startDateTime | Date/time that the task execution started.
Data type: String |
| taskExecutionURL | URL of the task to execute. Data type: String |
| triggerType | The way the orchestration task was started.
Valid values:
Data type: String |
| url | URL of the associated orchestration tool's orchestration task.
Data type: String |
Example: Sample cURL request with resource=task_execution
curl -X GET \
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=task_execution' \
-H 'Accept: application/json'\
-u 'username':'password'{
"result": {
"number": 40,
"url": "https://jenkins.mycompany.com:8080/job/Mobile-Platform-CI/40/",
"startDateTime": "1970-01-01T08:15:30-05:00",
"endDateTime": "1970-01-01T08:25:30-05:00",
"triggerType": "upstream",
"result": "Success",
"orchestrationTaskDetails": {
"name": "Mobile-Platform-CI",
"url": "https://jenkins.mycompany.com:8080/job/Mobile-Platform-CI/"
}
}
}Example: Sample cURL request with resource=orchestration_task
curl -X GET \
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=orchestration_task' \
-H 'Accept: application/json'\
-u 'username':'password'
{
"result": {
"name": "Mobile-Platform-CI",
"url": "https://jenkins.mycompnay.com:8080/job/Mobile-Platform-CI/"
}
} Example: Sample cURL request with resource=callback
curl -X GET \
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=task_execution' \
-H 'Accept: application/json' \
-u 'username':'password'
{
"result": {
"callbackURL": "http://127.0.0.1:8090/jenkins/sn-devops/9b0feb79-f0b9-4661-83ef-2861b8924784",
"orchestrationTaskURL": "http://127.0.0.1:8090/jenkins/job/felipe-downstream/",
"orchestrationTaskDetails": {
"message": "Started by upstream project \"felipe-upstream\" build number 27",
"triggerType": "upstream"
}
}
} DevOps - GET /devops/orchestration/stepMapping
Verifies that the information being passed is valid for the creation of an orchestration task and is valid for association to a previously created step.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/stepMapping
Default URL: /api/sn_devops/devops/orchestration/stepMapping
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| branchName | Name of the branch associated with the orchestration task. Data type: String |
| isMultiBranch | If the orchestration tool is Jenkins, flag that indicates whether the project is of type Multibranch. Valid values:
Data type: Boolean Default: false |
| parentStageName | If the orchestration task is a child nested inside a parent orchestration task,
the name of the parent orchestration task. Data type: String |
| parentStageURL | If the orchestration task is a child nested inside a parent orchestration task,
the URL of the parent orchestration task. Data type: String |
| orchestrationTaskName | Required. Name of the orchestration task. Data type: String |
| orchestrationTaskURL | Required. URL of the orchestration task. Note: Must be percent (%) encoded, such
as https%3A%2F%2Fjenkins.mycompany.com%3A8080%2Fjob%2FMobile-Platform-deploy%2F. Data type: String |
| testConnection | Flag that indicates whether to test the end-to-end connection between the
instance and the DevOps tool. Valid values:
Data type: Boolean Default: false |
| toolId | Required. Sys_id of the orchestration tool. Located in
the Orchestration Tool [sn_devops_orchestration_tool] table. Data type: String |
| toolType | Required. Type of tool. Valid values: jenkins Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Element | Description |
|---|---|
| status | Flag that indicates whether the verification was successful. Valid values:
Data type: Boolean |
| stepValid | Flag that indicates whether the information sent is valid. Valid values:
Data type: Boolean |
Example: Sample cURL request
curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins "
-H "Accept: application/json" \
-u "username":"password"
Results if information is valid.
{
"result": {
"stepValid": true,
"status": "Success"
}
}Example: Sample cURL request
curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins "
-H "Accept: application/json" \
-u "username":"password"
Results if information is invalid.
{
"result": {
"stepValid": false,
"status": "Success"
}
DevOps - GET /devops/plan/schema
Returns the schema object for a specific plan: app, version, or work item.
Once you have the required schema object, use it to create the request body for your corresponding POST call; POST /plan/app, POST /plan/version, or POST /plan/workitem.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/plan/schema
Default URL: /api/sn_devops/devops/plan/schema
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| resource | Type of resource schema to return. Valid values (not case-sensitive):
Data type: String |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Invalid or missing authentication. |
| 404 | Not Found. The specified record couldn't be found. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| app | Description of the application to associate with the version.
Data type: Object |
| app.createdDateTime | Date/time the application was created in the source DevOps tool.
Data type: String |
| app.id | Unique identifier of the
application. Generated by the source planning tool.
Data type: String |
| app.shortDescription | Brief
description of the associated application.
Data type: String |
| app.team | Description of
the team associated with the application.
Data type: Object |
| app.team.id | Unique
identifier of the team associated with the application. Generated by the source
planning tool.
Data type: String |
| app.team.name | Name of the team associated with the
application.
Data type: String |
| app.url | URL of the application on the source planning tool
site.
Data type: String |
| assignedTo | Description of the person to which the work item is assigned.
Data type: Object |
| assignedTo.email | Email address of the person assigned to the
work item.
Data type: String |
| assignedTo.id | Unique identifier of the person assigned to
the work item.
Data type: String |
| assignedTo.name | Name of the person assigned to the work
item.
Data type: String |
| assignedTo.userName | User name of the person assigned to the
work item.
Data type: String |
| createDateTime | Date and time that the application, version, or work item record was
created. Data type: String |
| id | Unique identifier of the application, version, or work item. Generated by the
source planning tool. Data type: String |
| name | Name of the application. Data type: String |
| path | Relative path to the application. Data type: String |
| shortDescription | Brief description of the application, version, or work item. Data type: String |
| state | State of the work item. Generated by the source
planning tool.
Data type: String |
| team | Description of
the team associated with the application.
Data type: Object |
| team.id | Unique
identifier of the team associated with the application. Generated by the source
planning tool.
Data type: String |
| team.name | Name of the team associated with the
application.
Data type: String |
| type | Type of work item. Generated by the planning tool. Data type: String |
| url | URL to use to access the application, version, or work item. Data type: String |
| version | Array that describes the version. Data type: Object |
| version.app | Description of the application to associate with the version.
Data type: Object |
| version.app.createdDateTime | Date/time that the version was created on the source DevOps tool.
Data type: String |
| version.app.id | Unique identifier of the
application. Generated by the source planning tool.
Data type: String |
| version.app.shortDescription | Brief
description of the associated application.
Data type: String |
| version.app.team | Description of
the team associated with the application.
Data type: Object |
| version.app.team.id | Unique
identifier of the team associated with the application. Generated by the source
planning tool.
Data type: String |
| version.app.team.name | Name of the team associated with the
application.
Data type: String |
| version.app.url | URL of the application on the source planning tool
site.
Data type: String |
| version.createdDateTime | Date/time that the version was created on the source DevOps tool.
Data type: String |
| version.id | Unique identifier of
the version. Generated by the source planning tool.
Data type: String |
| version.shortDescription | Brief
description of the associated version.
Data type: String |
| version.url | URL of the version
on the source planning tool site.
Data type: String |
Example: Sample cURL request for resource=app
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=app" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"{
"result": {
"id": "PRODUCT1234",
"shortDescription": "Mobile UI",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"team": {
"name": "Mobile UI",
"id": "f0ca45679323008b52f3b457415ae6"
},
"url": "https://jira.com/mycompany/browse/PRODUCT-125"
}
}Example: Sample cURL request for resource=version
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=version" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"id": "REL1234",
"shortDescription": "APIs Release",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"app": {
"id": "PRODUCT1234",
"shortDescription": "Mobile UI",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"team": {
"name": "Mobile UI",
"id": "f0ca45679323008b52f3b457415ae6"
},
"url": "https://jira.com/mycompany/browse/PRODUCT-125"
},
"url": "https://jira.com/mycompany/browse/REL-125"
}
}Example: Sample cURL request for resource=work_item
curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=work_item" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"id": "STR1234",
"type": "Story",
"shortDescription": "Planning API Spec",
"state": "In-progress",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"assignedTo": {
"name": "Leo Neo",
"userName": "lenn",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"email": "lenn@smithworksinc.com"
},
"version": {
"id": "REL1234",
"shortDescription": "APIs Release",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"app": {
"id": "PRODUCT1234",
"shortDescription": "Mobile UI",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"team": {
"name": "Mobile UI",
"id": "f0ca45679323008b52f3b457415ae6"
},
"url": "https://jira.com/mycompany/browse/PRODUCT-125"
},
"url": "https://jira.com/mycompany/browse/REL-125"
},
"app": {
"id": "PRODUCT1234",
"shortDescription": "Mobile UI",
"createdDateTime": "1970-01-01T08:15:30-05:00",
"team": {
"name": "Mobile UI",
"id": "f0ca45679323008b52f3b457415ae6"
},
"url": "https://jira.com/mycompany/browse/PRODUCT-125"
},
"url": "https://jira.com/mycompany/browse/HALOKEY-25"
}
}DevOps - POST /devops/artifact/registration
Enables orchestration tools to register artifacts into a ServiceNow instance.
- If the toolId is passed in the request, the endpoint validates that the tool exists within the instance. It also checks if the artifact repository specified in artifacts.repositoryName exists, and if not, creates it under the associated artifact tool.
- If the toolId is not passed in the request, a repository is created but it is not linked to any artifact tool.
- It then checks if the artifact specified in artifacts.name already exists, and if not, creates it under the associated repository.
- If the artifact.version is passed in the request:
- If it does not exist, a new artifact version record is created in the associated Artifact Version [sn_devops_artifact_version] table.
- The endpoint then looks for associated task executions based on the provided build details (pipelineName or projectName, taskExecutionNumber, branchName, and stageName) and the orchestrationToolId parameter.
- If a task execution is found, and its post-processing is complete, the artifact version is linked to the task execution and stored in the Artifact to TaskExecution [sn_devops_m2m_artifact_execution] table. Commits linked to these task executions are also associated to the artifact version and stored in the Artifact Version to Commit [sn_devops_m2m_artifact_version_commit] table. Any commits that are linked to previous task executions that did not create an artifact, are also associated with the artifact version.
- If a task execution is found, and its post-processing is not complete, then the request is persisted in the Artifact Staged Request [sn_devops_artifact_staging] table. The staged request contains a reference to the task execution.
- If a task execution is not found, the request is persisted in the staging table. The staged request contains the build details.
- If the artifact.version is not passed in, then depending on the tool configuration, the artifact version is either retrieved by calling the /devops/tool/artifact endpoint if your artifact tool supports webhooks or through a custom subflow that retrieves the artifact version from the artifact tool.
For additional information on artifacts, see Using DevOps change acceleration for releases.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/artifact/registration
Default URL: /api/sn_devops/devops/artifact/registration
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| orchestrationToolId | Required. Sys_id of the orchestration tool associated with the artifact. The endpoint uses this information to locate task execution information. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| toolId | Sys_id of the artifact tool associated with the artifact. Data type: String Table: Artifact Tool [sn_devops_artifact_tool] |
| Name | Description |
|---|---|
| artifacts | At least one entry required. Array of objects in which each object uniquely identifies an artifact version to register. Data type: Array of Objects |
| artifacts.name | Required. Artifact file name. Data type: String Maximum length: 160 characters |
| artifacts.repositoryName | Required. Artifact repository name. If the specified repository record does not exist, it is created. Data type: String Maximum length: 160 characters |
| artifacts.semanticVersion | Semantic version of the artifact. Data type: String Format: MAJOR.MINOR.PATCH Examples of possible values:
Maximum length: 160 characters Default: Null |
| artifacts.version | Required if toolId is not passed. Artifact version. Data type: String Format: MAJOR.MINOR Maximum length: 160 characters Default: Null |
| branchName | Required if it is a multi-branch project. Name of the branch in the repository where the artifact is stored. Data type: String Maximum length: 160 Default: Null |
| pipelineName | Required if projectName is not passed. Pipeline name. Data type: String Maximum length: 160 Default: Null |
| projectName | Required if pipelineName is not passed. Free-form project name. Data type: String Maximum length: 160 Default: Null |
| stageName | Required if pipelineName is passed. Stage name. Data type: String Maximum length: 160 Default: Null |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Success. Success with response body. |
| 201 | Created. Success with response body. |
| 400 | Bad Request. The request URI does not match the APIs in the system, or the operation failed for unknown reasons. Invalid headers can also cause this error. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| response | Results of the artifact registration request. Data type: Object |
| response.artifact | Results for each processed artifact. Data type: Object |
| response.artifact.create | If the request created artifact records, the list of sys_ids of the created records. Data type: Array of Objects Table: Artifacts [sn_devops_artifact] |
| response.artifact.create.id | Sys_id of the artifact record created by the request. Data type: String |
| response.artifact.found | If an artifact already exists in the Artifacts table, the list of sys_ids of the existing artifact records. Note: No modifications are made to existing packages. Data type: Array of Objects |
| response.artifact.found.id | Sys_id of the existing artifact record. Data type: String |
| response.artifact.update | Currently unused |
| response.artifact.update.id | Currently unused |
| response.artifact_register_requests | Results for any artifacts register requests that have not completed processing and have been stored in the Artifact Staged Request table. Data type: Object |
| response.artifact_register_requests.create | If the request created artifact staging records, the list of sys_ids of the created records. Data type: Array of Objects |
| response.artifact_register_requests.create.id | Sys_id of the artifact staging record created by the request. Data type: String |
| response.artifact_register_requests.found | If artifacts already have associated artifact staging records, the list of sys_ids of the existing artifact staging records. Note: No modifications are made to existing packages. Data type: Array of Objects |
| response.artifact_register_requests.found.id | Sys_id of an existing artifact staging record. Data type: String |
| response.artifact_register_requests.update | Currently unused |
| response.artifact_register_requests.update.id | Currently unused |
| response.artifact_repository | Results for any artifact repository records that were manipulated during the processing of the request. Data type: Object |
| response.artifact_repository.create | If artifact repositories were created by the request, the list of sys_ids of the created records. Data type: Array of Objects |
| response.artifact_repository.create.id | Sys_id of the artifact repository record created by the request. Data type: String |
| response.artifact_repository.found | If artifact repository records used in the register request already exist, the list of sys_ids of the existing records. Note: No modifications are made to existing packages. Data type: Array of Objects |
| response.artifact_repository.found.id | Sys_id of an existing artifact repository record used by the request. Data type: String |
| response.artifact_repository.update | If the endpoint updates the track flag on a repository to true (from false), the list of sys_ids of the repository records that were modified. Data type: Array of Objects |
| response.artifact_repository.update.id | Sys_id of the repository record whose track flag was modified. Data type: String |
| response.artifact_version | Results for any artifact version records that were manipulated during the processing of the request. Data type: Object |
| response.artifact_version.create | Results for any artifact version records that were created during the processing of the request. Data type: Array of Objects |
| response.artifact_version.create.id | Sys_id of the artifact version record created by the request. Data type: String |
| response.artifact_version.found | If artifact version records used in the register request already exist, the list of sys_ids of the existing records. Data type: Array of Objects |
| response.artifact_version.found.id | Sys_id of the existing artifact version record used by the request. Data type: String |
| response.artifact_version.update | Currently unused |
| response.artifact_version.update.id | Currently unused |
| status | Status of the registration request. Possible values:
Data type: String |
Example: Sample cURL request
curl -X POST \
'https://instance.servicenow.com/api/sn_devops/devops/artifact/registration?toolId=391b4ff6dba24010bc8cdd384b96198f&orchestrationToolId=99d70b36dba24010bc8cdd384b961985' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password' \
-d ' {"artifacts": [\
{\
"name": "sa-web.jar",\
"version": "3.1",\
"semanticVersion": "3.1.0",\
"repositoryName": "services-1031"\
},\
{\
"name": "sa-frontend.jar",\
"version": "3.2",\
"semanticVersion": "3.2.0",\
"repositoryName": "services-1031"\
}\
],\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
}]'{
"result": {
"status": "Success",
"response": {
"artifact_repository": {
"create": [
{
"id": "2e50ba8bdbaa4010bc8cdd384b961988"
}
],
"update": [],
"found": [
{
"id": "2e50ba8bdbaa4010bc8cdd384b961988"
}
]
},
"artifact": {
"create": [
{
"id": "6a50f603dbea4010bc8cdd384b96193d"
},
{
"id": "2e50f603dbea4010bc8cdd384b96193f"
}
],
"update": [],
"found": []
},
"artifact_version": {
"create": [
{
"id": "a650f603dbea4010bc8cdd384b96193e"
},
{
"id": "6250f603dbea4010bc8cdd384b961940"
}
],
"update": [],
"found": []
},
"artifact_register_requests": {
"create": [
{
"id": "6250f603dbea4010bc8cdd384b96193f"
},
{
"id": "6650f603dbea4010bc8cdd384b961940"
}
],
"update": [],
"found": []
}
}
}
}DevOps - POST /devops/onboarding/app
Creates an onboarding app event that is asynchronously processed by the DevOps service.
- Create applications.
- Associate DevOps objects such as, plan, repository, and pipeline, to an application.
- Create a change step record and associate a change approval process to a pipeline.
All of these actions are tool and capability specific. The following table outlines the actions available for each supported tool.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/onboarding/app
Default URL: /api/sn_devops/devops/onboarding/app
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| apps | Array of objects that define the apps to create within the associated ServiceNow instance. Data type: Array |
| apps.bussinessApp | Name of the cmdb_ci_business_app to which map the application. This ties the
DevOps application to the specified CMDB application. Data type: String |
| apps.name | Required. User friendly name of the application to create to create. An app is
a DevOps product container object that ties plans, repositories, and
pipelines together. Data type: String |
| credentials | Required. Credentials to use for the webhook creation. The created webhook is
used by the tool to send notifications. Data type: Object |
| credentials.name | Required. ServiceNow user ID of the user making the endpoint request. This user must have the devops.integration.user role. Starting with version 1.34.1, this user must have the sn_devops.admin role. Data type: String Table: User [sys_user] |
| credentials.password | Required. Password of the user specified in the
credenitals.name parameter. Data type: String |
| pipelines | List of pipelines to associate with applications. Data type: Array of Objects |
| pipelines.app | Required if a pipelines object is specified. Name of the
application to associate with the plan specified in the
pipelines.name parameter. The application must have already
been created or be specified in the apps object of this
request. Data type: String |
| pipelines.changeSteps | Change steps to create for the pipeline specified in the pipelines.name field. Data type: Array of Objects |
| pipelines.changeSteps.changeApprovalGroup | Required if a changeSteps object is specified. Name of the change approval group to associate with the pipeline. This group must already exist on the ServiceNow instance. Data type: String Table: Group [sys_user_group] |
| pipelines.changeSteps.changeControlledBranches | Comma-separated list of code branches that are under change control. This only applies for multi branch support. Data type: String Default: * (all branches) |
| pipelines.changeSteps.changeType | Required if a changeSteps object is specified. Type of change request to create. Data type: String Table: In the Type field of the Change Request [change_request] table. |
| pipelines.changeSteps.name | Required if a changeSteps object is specified. Name of the
step to create. The step name must match the name of the corresponding step in the
orchestration tool’s pipeline. Data type: String |
| pipelines.changeSteps.type | Required if a changeSteps object is specified. Type of step to create. Data type: String Table: In the Type field of the Steps [sn_devops_step] table. |
| pipelines.name | Required if a pipelines object is specified. Name of the
pipeline to associate with the application specified in
pipelines.app parameter. This pipeline must already be
discovered on the ServiceNow instance. Data type: String |
| pipelines.project | Required if a pipelines object is specified and the pipelines.tool supports projects entity (for example, the ADO tool). Project to associate with the pipeline to create a unique pipeline/tool
identifier. Parameter value must derive from a project in the Project [sn_devops_project] table.Data type: String |
| pipelines.tool | Required if a pipelines object is specified. Tool to
associate with the pipeline to create a unique pipeline/tool identifier. Data type: String |
| plans | List of plans to associate with an application. Data type: Array of Objects |
| plans.apps | Required if a plans object is specified. Names of
applications to associate with the plan specified in the
plans.name parameter. These applications must have already
been created or be specified in the apps object of this
request. Data type: Array of Strings |
| plans.name | Required if a plans object is specified. Name of the plan
to associate with the application specified in plans.app
parameter. This plan must already be discovered on the ServiceNow instance. Data type: String |
| plans.project | Required if a plans object is specified and the plans.tool supports projects entity (for example, the ADO tool). Tool to associate with the pipeline to create a unique plans/tool identifier.
Parameter value must derive from a project in the Project [sn_devops_project] table.Data type: String |
| plans.tool | Required if a plans object is specified. Tool to associate
with the plan to create a unique plan/tool identifier. Data type: String |
| repositories | List of repositories associated with an application. If the repositories object contains an app parameter, then it maps the repository to the application. Data type: Array of Objects |
| repositories.app | Required if a repositories object is specified. Name of
the application to associate with this repository. The application must have already
been created or be specified in the apps object of this
request. Data type: String |
| repositories.name | Required if a repositories object is specified. Name of
the repository to associate with the application specified in
repositories.app parameter. This repository must already be
discovered on the ServiceNow instance. Data type: String |
| repositories.project | Required if a repositories object is specified and the repositories.tool supports a projects entity (for example, the ADO tool). Tool to associate with the repositories to
create a unique repository/tool identifier. Parameter value must derive from a project in the Project [sn_devops_project] table.Data type: String |
| repositories.tool | Required if a repositories object is specified. User
friendly tool name to associate with the repository to create a unique
repository/tool identifier. The tool must already be created on the ServiceNow instance. Data type: String |
| artifactRepositories.app | Required if the artifactRepositories object is specified. Name of the application to associate with this artifactRepositories. The application must have already been created or be specified in the
apps object of this request.Data type: String |
| artifactRepositories.name | Required if the artifactRepositories object is specified. Name of the artifactRepositories to associate with the application specified in artifactRepositories.app parameter. This
artifactRepositories must already be discovered on the ServiceNow instance.Data type: String |
| artifactRepositories.tool | Required if the artifactRepositories object is specified. User friendly tool name to associate with the artifactRepositories to create a unique artifactRepositories /tool identifier. The tool must
already be created on the ServiceNow instance.Data type: String |
| artifactRepositories.project | Required if the artifactRepositories object is specified and the repositories.tool supports projects entity (for example, the ADO tool). Tool to associate with the
artifactRepositories to create a unique pipeline/tool identifier. Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 202 | Onboarding request was successfully created. |
Response body parameters
| Name | Description |
|---|---|
| result | Results of the onboarding request. Data type:
Object |
| result.code | HTTP status code. Data type: String |
| result.details | Details about the onboarding request. Data type: String |
| result.errors | Description of any error that occurred. Data type: Object |
| result.error.message | Error message. Data type: String |
| result.onboardingRequestID | Unique identifier of the onboarding request. Use this value when calling the
/devops/onboarding/status endpoint to obtain the status of the
associated onboarding process. Data type: String |
| result.status | Status of the onboarding request, either Success or Failed. Data type: String |
Example: cURL request
This example creates the application Bike Rental Service and associates it with the Jenkins pipeline Bike Rentals, the GitHub repository nowDevops01/CorpSite, and the Azure plan testPlan_Bike_Rental.
curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/app" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \
-d "{
"apps": [
{
"name": "Bike Rental Service"
}
]
"pipelines": [
{
"tool": "Primary Jenkins",
"name": "Bike Rentals",
"app": "Bike Rental Service",
"changeSteps": [
{
"name": "Prod",
"type": "deploy",
"changeApprovalGroup": "Change Management",
"changeType": "normal"
}
]
}
],
"repositories": [
{
"tool": "Primary GitHub",
"name": "nowDevops01/CorpSite",
"app": "Bike Rental Service"
}
]
"plans": [
{
"tool": "Primary Azure",
"name": "testPlan_Bike_Rental",
"project": "DemoProjecttt",
"apps": [
"Bike Rental Service"
]
}
]
"artifactRepositories": [
{
"tool": "AdoTool",
"name": "empb5-sonar",
"apps": [
"appXXXXtz"
]
}
]
"credentials" : {
"name": "devops_user",
"password": "devops_password"
}
} Output:
{
"result":{
"status": "Success",
"details": "Onboarding request has been created. Please use the /status api and the onboarding request number to get the status of the request",
"onboardingRequestID": "IBE0001045",
"code": "202"
}
} DevOps - POST /devops/onboarding/tool
Creates an onboarding tool event that is asynchronously processed by the DevOps service.
- Creates the tool within the associated ServiceNow instance
- Connects to the tool
- Tries to configure the tool (only if the connection is successful)
- Discovers the tool (only if the connection is successful)
The return results for this endpoint only indicate whether the request was posted, it does not indicate whether the associated tools were created. The actual tool creation is processed asynchronously. To obtain the status of the tool creation and all other actions, you must call the /devops/onboarding/status endpoint and pass in the onboardingRequestID parameter that is returned by this endpoint.
Before you are able to access this endpoint, your admin must have configured the DevOps connection and credential alias (CreateDevOpsTool) to setup tools in the instance. For details, see Install DevOps Change Velocity. In addition, the calling entity must have the devops.integration.user role.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/onboarding/tool
Default URL: /api/sn_devops/devops/onboarding/tool
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| credentials | Required. Credentials to use for the webhook creation. The tool uses the
created webhook to send notifications. Data type: Object |
| credentials.name | Required. ServiceNow identifier of the user making the endpoint request. This user must have the devops.integration.user role. Starting with version 1.34.1, this user must have the sn_devops.admin
role. Data type: String Table: User [sys_user] |
| credentials.password | Required. Password of the user specified in the
credenitals.name parameter. Data type: String |
| tools | Required. Tools to create within the associated ServiceNow instance. You can create one or more tools in a single request. Data type: Array of Objects |
| tools.name | Required. User friendly name or label of the tool to create. This name is used
to identify the tool in the DevOps service. Data type: String |
| tools.password | Required except for Agile tool. Password to use to access the tool. Supported
authentications are basic and token; OAuth is not supported. Data type: String |
| tools.type | Required. Type of tool to create, such as GitHub or BitBucket. The specified
value must be one of the Tool labels in the Tool Integrations
[sn_devops_tool_integration] table. Data type: String |
| tools.useMidServer | Flag that indicates whether the tool connects through a MID Server. Valid values:
Data type: Boolean |
| tools.username | Required except for Agile tool. User name to use to access the tool through
this endpoint. Data type: String |
| tools.url | Required except for Agile tool. URL of the tool to create. The DevOps service uses this URL to integrate with the tool. If using the 'Azure DevOps' tool, tools.url can contain either the ADO Organization URL or the ADO Project URL. When providing an ADO Organization URL, the API discovers all projects under the specified organization and does not configure any projects. When providing an ADO Project URL, the API
discovers entities related to the project like (pipelines, repositories, and plans) and also configures a project if the credentials object is present. To explicitly tell the API to skip the
project configuration, configure a flag configureTool (type: boolean) to Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 202 | Onboarding request was successfully created. |
Response body parameters
| Name | Description |
|---|---|
| result | Results of the onboarding request. Data type:
Object |
| result.code | HTTP status code. Data type: String |
| result.details | Detailed message about the onboarding request. Data type: String |
| result.errors | Description of any error that occurred. Data type: Object |
| result.error.message | Error message. Data type: String |
| result.onboardingRequestID | Unique identifier of the onboarding request. Use this value when calling the
/devops/onboarding/status endpoint to obtain the status of the
associated tool onboarding process. Data type: String |
| result.status | Status of the onboarding request, either Success or Failed. Data type: String |
Example: cURL request
The following example shows how to onboard GitHub.
curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/tool" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \
-d {
"tool":[{
"name": "Primary GitHub",
"type": "GitHub",
"url": "https"//api.github.com",
"username": "username",
"password": "password",
"useMidServer": false
}]
"credentials" : {
"name": "devops_user",
"password": "devops_password"
}
}{
"result":{
"status": "Success",
"details": "Onboarding request has been created. Please use the /status api and the onboarding request number to get the status of the request",
"onboardingRequestID": "IBE0001041",
"code": "202"
}
}DevOps - POST /devops/orchestration/changeControl
Registers a callback with a ServiceNow instance for an orchestration task under change control, which can be called once a decision has been made on the change request.
Before you call this endpoint, you must have an orchestration task created in your ServiceNow instance. You can create this task either through Discovery or by calling the DevOps - POST /devops/orchestration/stepMapping endpoint. You must also ensure that the orchestration task is associated to a previously defined pipeline step and that change control is enabled (by selecting the Change control option on the App Stage form.) For details, see Accelerating DevOps change.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/changeControl
Default URL: /api/sn_devops/devops/orchestration/changeControl
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| toolId | Required. Sys_id of the DevOps tool for which to place the specified task under change control. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| toolType | Type of tool. Valid value: Any value that identifies the tool, such as "jenkins". Data type: String |
| Name | Description |
|---|---|
| callbackURL | Required. URL that the ServiceNow instance can call back once the
associated change request approval process is complete. This callback should let the
pipeline execution continue or not, based on the approval result.
Data type: String |
| changeRequestDetails | Name-value pairs of the fields to set when closing a change request. This object can contain any fields in the Change Request record except the following:
If these fields are included in the request, the endpoint returns a 400 error and the change request is not updated. Also, if you include fields that require other mandatory fields to be set, and those fields are not sent, the request will fail during later processing of the pipeline. This failure is noted in the work notes of the change request, along with an error message for that particular change request, such as: Change request update failed with reason: <Error Message from platform>. Canceling change request and the related step execution. You can also pass the boolean parameter
setCloseCode in this object to specify whether to set closure information on the associated Change Request record.
Data type: Object |
| isMultiBranch | If the orchestration tool is Jenkins, flag that indicates whether the project is of type Multibranch. Valid values:
Data type: Boolean Default: false |
| orchestrationTaskDetails | Required. Description of the orchestration task.
Data type: Object |
| orchestrationTaskDetails.message | Free-form text
message.
Data type: String |
| orchestrationTaskDetails.triggerType | Required. The way the orchestration task was started.
Valid values:
Data type: String |
| orchestrationTaskDetails.upstreamTaskExecutionURL | Required if triggerType is set to upstream. Upstream task execution URL.
For example: https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/ Data type: String |
| orchestrationTaskURL | Required. URL of the orchestration task for which to create the call back.
For example: https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ Data type: String |
| parentNode | If the orchestration task is a child nested inside a parent orchestration task, this value contains the parent node details. Data type: Object |
| parentNode.id | Unique ID for the parent node. In Jenkins, this value corresponds to a pipeline stage ID. Data type: String |
| parentNode.name | Name of the parent node. In Jenkins, this value corresponds to a pipeline stage name. Data type: String |
| parentNode.upstreamStageName | Name of the parent node’s upstream orchestration task. In Jenkins, this value corresponds to a pipeline stage name. Data type: String |
| parentNode.upstreamTaskExecutionURL | URL of the parent node’s upstream task execution. In Jenkins, this value corresponds to a pipeline stage execution URL. Data type: String |
| parentStageName | If the orchestration task is a child nested inside a parent orchestration task,
the name of the parent orchestration task. Data type: String |
| parentStageURL | If the orchestration task is a child nested inside a parent orchestration task,
the URL of the parent orchestration task. Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml.
Default: application/json |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 201 | Request completed successfully. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Invalid or missing authentication. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| changeControl | Flag that indicates whether the orchestration task is under change control. Possible values:
Data type: Boolean |
Example: cURL request
curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
\"orchestrationTaskURL\":\"https://jenkins.mycompany.com:8080/orchestration task/Mobile-Platform-deploy/\",
\"callbackURL\":\"https://jenkins.mycompany.com:8080/sn-devops/964aca59-0cae-4d9b-a36d-5929f426cf31\",
\"orchestrationTaskDetails\":{
\"message\":\"Started by upstream project \\\"Mobile-Platform-test\\\" build number 40\",
\"triggerType\":\"upstream\",
\"upstreamTaskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\"}
}"Response body.
{
"result": {
"changeControl": true,
"status": "Success"
}
}Example: cURL request
This example shows how to pass fields in the changeRequestDetails object when closing a change request.
curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
"callbackURL":"http://192.168.0.4:3000/jenkins/sn-devops/pipeline_839b7605-b98d-4831-bc87-96829de7da37",
"orchestrationTaskURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests#deploy/",
"isMultiBranch":"false",
"orchestrationTaskName":"java_sample_tests#deploy",
"orchestrationTaskDetails":{
"triggerType":"upstream",
"upstreamTaskExecutionURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests/129/execution/node/35/wfapi/describe",
"taskExecutionURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests/129/execution/node/50/wfapi/describe"
},
"changeRequestDetails":{
"setCloseCode":false,
"attributes":{
"sys_created_by":"1832fbe1d701120035ae23c7ce610369",
"sys_updated_by":"56826bf03710200044e0bfc8bcbe5dca",
"requested_by":{
"name":"test user1"
},
"watch_list":[
{
"name":"test user1"
},
{
"name":"test user2"
},
{
"name":"Alejandra Prenatt"
},
"56826bf03710200044e0bfc8bcbe5dca"
],
"work_notes_list":[
"56826bf03710200044e0bfc8bcbe5dca",
"46c6f9efa9fe198101ddf5eed9adf6e7",
"d8f57f140b20220050192f15d6673a98"
],
"assigned_to":"1832fbe1d701120035ae23c7ce610369",
"category":"Service",
"sys_created_on":"2021-02-09 18:58:41",
"priority":"2",
}
}
}"Response body.
{
"result": {
"changeControl": true,
"status": "Success"
}
}DevOps - POST /devops/orchestration/stepMapping
Verifies that the information being passed is valid for the creation of an orchestration task and is valid for association to a previously created step. If both are valid, it creates the orchestration task and makes the association.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/stepMapping
Default URL: /api/sn_devops/devops/orchestration/stepMapping
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| toolId | Required. Sys_id of the orchestration tool. Located in
the Orchestration Tool [sn_devops_orchestration_tool] table. Data type: String |
| toolType | Required. Type of tool. Valid values: jenkins Data type: String |
| Name | Description |
|---|---|
| branchName | Name of the branch associated with the orchestration task. Data type: String |
| isMultiBranch | If the orchestration tool is Jenkins, flag that indicates whether the project is of type Multibranch. Valid values:
Data type: Boolean Default: false |
| parentNode | If the orchestration task is a child nested inside a parent orchestration task,
this value contains the parent node details. Data type: Object |
| parentNode.id | Unique ID for the parent node. In Jenkins, this value corresponds to a pipeline stage ID. Data type: String |
| parentNode.name | Name of the parent node. In Jenkins, this value corresponds to a pipeline stage name. Data type: String |
| parentNode.upstreamStageName | Name of the parent node’s upstream orchestration task. In Jenkins, this value corresponds to a pipeline stage name. Data type: String |
| parentNode.upstreamTaskExecutionURL | URL of the parent node’s upstream task execution. In Jenkins, this value corresponds to a pipeline stage execution URL. Data type: String |
| parentStageName | If the orchestration task is a child nested inside a parent orchestration task,
the name of the parent orchestration task. Data type: String |
| parentStageURL | If the orchestration task is a child nested inside a parent orchestration task,
the URL of the parent orchestration task. Data type: String |
| orchestrationTaskName | Required. Name of the orchestration task. This is the same task referenced in the orchestrationTaskURL.
Data type: String |
| orchestrationTaskURL | Required. URL of the orchestration task.
For example: https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 201 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Element | Description |
|---|---|
| status | Flag that indicates whether the verification was successful. Valid values:
Data type: Boolean |
| stepValid | Flag that indicates whether the information sent is valid. Valid values:
Data type: Boolean |
Example: Sample cURL request
curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "Accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
\"orchestrationTaskURL\":\" http://127.0.0.1:8090/jenkins/job/CorpSite/job/primary#deploy PROD/\",
\"orchestrationTaskName\":\" primary#deploy PROD\"
}"Results if information is valid.
{
"result": {
"stepValid": true,
"status": "Success"
}
}Results if information is invalid.
{
"result": {
"stepValid": false,
"status": "Success"
}
}DevOps - POST /devops/package/registration
Enables orchestration tools to create new artifact packages that contain specified artifact versions.
Artifact packages are used to display commits to change approvers when they view a change request. For commits to show in change requests, the package must be created in the stage prior to the stage containing the change approval.
Any artifact versions included in the package registration request should already be registered with DevOps. For details on registering artifact versions, see DevOps - POST /devops/artifact/registration.
- artifacts.pipelineName or artifacts.projectName
- artifacts.taskExecutionNumber
- artifacts.stageName
- artifacts.branchName
For additional information on artifact packages, see Using DevOps change acceleration for releases.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/package/registration
Default URL: /api/sn_devops/devops/package/registration
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| orchestrationToolId | Required. Sys_id of the orchestration tool associated with the artifact package. The endpoint uses this information to locate task execution information. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| toolId | Sys_id of the artifact tool associated with the artifact package. Data type: String Table: Artifact Tool [sn_devops_artifact_tool] |
| Name | Description |
|---|---|
| artifacts | At least one entry required. Array of objects in which each object uniquely identifies an artifact version to include in the package. Data type: Array of Objects |
| artifacts.branchName | Required if artifact.version is not passed and it is a multi-branch setup. Name of branch in which the artifact versions are stored. Data type: String Maximum length: 160 Default: Null |
| artifacts.name | Required. Artifact file name. Data type: String Maximum length: 160 characters |
| artifacts.pipelineName | Required if artifact.version and artifacts.projectName are not passed. Pipeline name. Data type: String Maximum length: 160 Default: Null |
| artifacts.projectName | Required if artifact.version and artifact.pipelineName are not passed. Free-form project name. Data type: String Maximum length: 160 Default: Null |
| artifacts.repositoryName | Required. Artifact repository name. Data type: String Maximum length: 160 characters |
| artifacts.stageName | Required if artifact.version is not passed. Stage name. Data type: String Maximum length: 160 Default: Null |
| artifacts.taskExecutionNumber | Required if artifact.version is not passed. Pipeline run number. Data type: String Default: Null |
| artifacts.version | Required if build details are not provided. Version of the artifacts. Data type: String Format: <Major>.<Minor> Default: Null |
| branchName | Required if it is multi-branch project. Name of the branch in the repository where the artifacts are stored. Data type: String Maximum length: 200 characters Default: Null |
| name | Required. Name of package. Data type: String Maximum length: 160 characters |
| pipelineName | Required if projectName is not passed. Pipeline name. Data type: String Maximum length: 160 characters Default: Null |
| projectName | Required if pipelineName is not passed. Free-form project name. Data type: String Maximum length: 160 Default: Null |
| stageName | Required if pipelineName is passed. Stage name. Data type: String Maximum length: 160 characters Default: Null |
| taskExecutionNumber | Required. Pipeline run number. Data type: String Maximum length: 128 characters Default: Null |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Success. Success with response body. |
| 201 | Created. Success with response body. |
| 400 | Bad Request. The request URI does not match the APIs in the system, or the operation failed for unknown reasons. Invalid headers can also cause this error. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| response | Results of the package registration request. Data type: Object |
| response.artifact_register_requests | Results for any register requests that have not completed processing and have been stored in the Artifact Staged Request [sn_devops_artifact_staging] table. Data type: Object |
| response.artifact_register_requests.create | If the request created package staging records, the list of sys_ids of the created staging records. Data type: Array of Objects |
| response.artifact_register_requests.create.id | Sys_id of the package staging record created by the request. Data type: String |
| response.artifact_register_requests.found | If the associated package staging records already exist, the list of sys_ids of the existing records. Note: No modifications are made to existing packages. Data type: Array of Objects |
| response.artifact_register_requests.found.id | Sys_id of an existing package staging record. Data type: String |
| response.artifact_register_requests.update | Currently unused. |
| response.artifact_register_requests.update.id | Currently unused. |
| response.sn_devops_m2m_artifact_version_package | Results for each artifact version associated with a package. Data type: Object |
| response.sn_devops_m2m_artifact_version_package.create | If the request created records linking artifact versions to packages, the list of sys_ids of the created records. Data type: Array of Objects Table: Artifact Version to Package [sn_devops_m2m_artifact_version_package] |
| response.sn_devops_m2m_artifact_version_package.create.id | Sys_id of the Artifact Version to Package record created by the request. Data type: String |
| response.sn_devops_m2m_artifact_version_package.found | If a linking record already exists in the Artifacts Version to Package table, the list of sys_ids of the existing linking records. Note: No modifications are made to existing records. Data type: Array of Objects |
| response.sn_devops_m2m_artifact_version_package.found.id | Sys_id of the existing Artifact Version to Package record. Data type: String |
| response.sn_devops_m2m_artifact_version_package.update | Currently unused. |
| response.sn_devops_m2m_artifact_version_package.update.id | Currently unused. |
| response.sn_devops_package | Results for any package records in the Packages [sn_devops_package] table that were manipulated during the processing of the request. Data type: Object |
| response.sn_devops_package.create | If package records were created by the request, the list of sys_ids of the created records. Data type: Array of Objects |
| response.sn_devops_package.create.id | Sys_id of the package record created by the request. Data type: String |
| response.sn_devops_package.found | If package records used in the register request already exist, the list of sys_ids of the existing records. Note: No modifications are made to existing records. Data type: Array of Objects |
| response.sn_devops_package.found.id | Sys_id of an existing package record referenced by the request. Data type: String |
| response.sn_devops_package.update | Currently unused. |
| response.sn_devops_package.update.id | Currently unused. |
| status | Status of the registration request. Possible values:
Data type: String |
Example: Sample cURL request
# Example passing the artifact version
curl -X POST "https://instance.servicenow.com/api/sn_devops/devops/package/registration?toolId=f0ca45679323008b52f3b457415ae6"\
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{\
"name": "sentimentpackage",\
"artifacts": [\
{\
"name": "sa-web.jar",\
"repositoryName": "services-1031",\
"version": "3.1"\
},\
{\
"name": "sa-frontend.jar",\
"repositoryName": "services-1031",\
"version": "9.2"\
}\
],\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
}"Response - package created:
"result": {
"status": "Success",
"response": {
"sn_devops_package": {
"create": [
{
"id": "0d57367a532e00107109ddeeff7b122a"
}
],
"update": [],
"found": []
},
"sn_devops_m2m_artifact_version_package": {
"create": [
{
"id": "c957367a532e00107109ddeeff7b122b"
},
{
"id": "8157367a532e00107109ddeeff7b122c"
}
],
"update": [],
"found": []
}
},
"responseCode": 201
}
}Example: Sample cURL request
# Example passing the build details
curl -X POST "https://instance.servicenow.com/api/sn_devops/devops/package/registration?toolId=f0ca45679323008b52f3b457415ae6"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{\
"name": "sentimentpackage",\
"artifacts": [\
{\
"name": "sa-web.jar",\
"repositoryName": "services-1031",\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
},\
{\
"name": "sa-frontend.jar",\
"repositoryName": "services-1031",\
"pipelineName": "spring-boot-fe",\
"taskExecutionNumber": "991",\
"stageName": "Build",\
"branchName": "primary"\
}\
],\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
}"Response - request created a staged package:
{
"result": {
"status": "Success",
"response": {
"artifact_register_requests": {
"create": [
{
"id": "4628f276532e00107109ddeeff7b1245"
},
{
"id": "4e28f276532e00107109ddeeff7b1245"
},
{
"id": "ce28f276532e00107109ddeeff7b1245"
}
],
"update": [],
"found": []
}
},
"responseCode": 201
}
}DevOps - POST /devops/tool/{capability}
Posts the passed in payload to the Inbound Event [sn_devops_inbound] table for processing by a custom DevOps subflow.
Call this endpoint from the associated webhook in your tool, specified by the passed in capability parameter. A custom subflow, to process the passed in payload, must already be defined in your ServiceNow instance. Based on a predefined schedule, the DevOps Master Flow picks up the webhook event information from the Inbound Event table and passes it to the custom subflow, which then process the payload. For more information on creating a custom subflow, see Creating DevOps subflows.
For additional information on test tool integration, see DevOps test tool integration.
Before calling this endpoint for a custom DevOps tool, you must implement the handleTool() and getNativeIdForOrchestrationTask() methods from sn_devops.DevOpsOrchestrationToolIntegrationHandler. For more information, see DevOpsOrchestrationToolIntegrationHandler - Scoped.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/tool/{capability}
Default URL: /api/sn_devops/devops/tool/{capability}
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| capability | Type of tool passing in the payload to store in the Inbound Event table. Valid values (not case-sensitive):
Data type: String |
| Name | Description |
|---|---|
| orchestrationToolId | Optional. Sys_id of the orchestration tool to which the related pipeline belongs. orchestrationToolId is required if the capability request parameter is set to
test or softwarequality.The value in the toolId parameter is the default orchestration tool if the orchestrationToolId parameter isn't passed. Data type: String |
| testType | Required if capability is set to test. Type of test being run. Data type: String Table: The valid values for this parameter are those in the Test type column of the Test Types [sn_devops_test_type] table. |
| toolId | Required. Sys_id of the tool for which the endpoint is being called. Data type: String |
| Name | Description |
|---|---|
| Tool dependant | The tool determines the content of the payload. |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 201 | Request completed successfully. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Invalid or missing authentication. |
| 500 | Internal Server Error. A logic error on the server-side code occurred. |
Response body parameters
| Name | Description |
|---|---|
| details | Entry for all error conditions.
Data type: Object |
| details.errors | Description of a single error.
Data type: Array of Objects |
| details.errors.message | Detailed error message.
Data type: String |
| status | Response status such as "Success" or "Data Error". Data type: String |
| sys_id | Sys_id of the record created in the Inbound Event table. Data type: String |
Example: Sample cURL request for artifact
curl -X POST "https://instance.service-now.com/api/sn_devops/v1/tool/artifact?toolId=3b59043ee4ea556e6850d61bc1a77e8a"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
"artifacts": [
{
"name": "sp-boot-app",
"version": "1.320",
"semanticVersion": "1.320.0",
"repositoryName": "sp-boot-app-repo"
}
],
"pipelineName": "spring-boot-app-gitea",
"taskExecutionNumber": "320",
"stageName": "Build"
}"Success response:
{
"result": {
"status": "Success",
"sysId": "33c57245dbf68410bc8cdd384b961966"
}
}Example: Sample cURL request for artifact
curl -X POST "https://instance.service-now.com/api/sn_devops/v1/tool/artifact?toolId=3b59043ee4ea556e6850d61bc1a77e8a"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{\
"timestamp": "2020-01-11T00:52:01.541+0000",\
"nodeId": "137BEECF-E1BF7BC1-90212D1C-0749A6D4-BC670F6B",\
"initiator": "admin/172.17.0.1",\
"repositoryName": "maven-releases29",\
"action": "CREATED",\
"component": {\
"id": "2a59043ed2ea556e6850d61bc1a77c7b",\
"componentId": "c3AtYm9vdC1hcHAtcmVwbzoyYTU5MDQzZWQyZWE1NTZlNjg1MGQ2MWJjMWE3N2M3Yg",\
"format": "maven2",\
"name": "sentiment-analysis-web",\
"group": "com.spboot",\
"version": "1.1"\
}\
}"Error response:
{
"result": {
"status": "Data Error",
"details": {
"errors": [
{
"message": "Unsupported capability type"
}
]
}
}
}Example: Sample cURL request for code
curl "https://instance.service-now.com/api/sn_devops/devops/tool/code?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"commits": [
{
"totalFiles": 1,
"nativeIdList": [
"49",
"50"
],
"id": "f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
"url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo/commit/f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
"apiURL": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_apis/git/repositories/8d7ba019-1739-431c-beb4-6025dd41f1ac/commits/f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
"message": "Fixes #49 and #50",
"committedDate": "2022-03-23T11:59:46Z",
"committer": {
"email": "xyz.abcd@email.com"
},
"details": [
{
"action": "edit",
"changes": "",
"file": "/LICENSE",
"additions": 0,
"deletions": 0,
"totalChanges": 0
}
]
}
],
"repository": {
"id": "8d7ba019-1739-431c-beb4-6025dd41f1ac",
"name": "DeployableRepo",
"url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo"
},
"branch": {
"name": "refs/heads/master",
"url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo?version=GBmaster"
}
}" \
--user 'username':'passsword'
Success response:
{
"result": {
"status": "Success",
"sysId: "1f8e586b879e85100f71cbfc0ebb3526"
}
}Example: Sample cURL request for orchestration
curl "https://instance.service-now.com/api/sn_devops/devops/tool/orchestration?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"toolId": "d450f5c887e609100f71cbfc0ebb35e5",
"buildNumber": 5676,
"nativeId": "adoTests/DeployableRepo#deploy#5676",
"pipelineId": "2",
"name": "adoTests/DeployableRepo#deploy",
"id": "adoTests/DeployableRepo#deploy#5676",
"url": "https://dev.azure.com/xyzabcd/_build/results?buildId=5676#deploy/",
"previousAttemptUrl": "",
"attemptNumber": 1,
"pipelineExecutionUrl": "https://dev.azure.com/xyzabcd/_build/results?buildId=5676",
"orchestrationTaskUrl": "https://dev.azure.com/xyzabcd/adoTests/_build?name=DeployableRepo#deploy",
"orchestrationTaskName": "adoTests/DeployableRepo #deploy",
"orchestrationTask": {
"orchestrationTaskName": "adoTests/DeployableRepo#deploy",
"toolId": "d450f5c887e609100f71cbfc0ebb35e5",
"orchestrationTaskURL": "https://dev.azure.com/xyzabcd/adoTests/_build?name=DeployableRepo#deploy",
"stageName": "deploy"
},
"upstreamTaskUrl": [],
"result": "building",
"startDateTime": "2022-03-23 12:01:31",
"log": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=5676&view=logs&j=5264e576-3c6f-51f6-f055-fab409685f20",
"logUrl": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=5676&view=logs&j=5264e576-3c6f-51f6-f055-fab409685f20"
}" \
--user 'username':'password'
Success response:
{
"result": {
"status": "Success",
"sysId: "37dfd8a7879e85100f71cbfc0ebb35c0"
}
}Example: Sample cURL request for plan
curl "https://instance.service-now.com/api/sn_devops/devops/tool/plan?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"id": "1053",
"type": "bug",
"state": "planned",
"shortDescription": "Title - Work Item test in 1.33.3",
"createdDateTime": "2022-03-23T10:45:53.02Z",
"parentId": "",
"url": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_workitems/edit/1053",
"version": {
"id": "adoTests",
"shortDescription": "adoTests",
"createdDateTime": "2022-03-23T10:46:12.355Z",
"url": "https://dev.azure.com/xyzabcd/adoTests",
"app": {
"id": "adoTests",
"shortDescription": "adoTests",
"createdDateTime": "2022-03-23T10:46:12.355Z",
"url": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_workitems/edit/1053"
}
},
"app": {
"id": "adoTests",
"shortDescription": "adoTests",
"createdDateTime": "2022-03-23T10:46:12.355Z",
"url": "https://dev.azure.com/xyzabcd/adoTests"
},
"native_type": "Issue",
"native_state": "To Do",
"assignedTo": {
"name": "Xyz Abcd",
"userName": "xyz.abcd@email.com",
"id": "84c92fcd-e08b-6a5f-a8a6-ccda27055560",
"email": "xyz.abcd@email.com"
},
"createdBy": {
"name": "Xyz Abcd",
"userName": "xyz.abcd@email.com",
"id": "84c92fcd-e08b-6a5f-a8a6-ccda27055560",
"email": "xyz.abcd@email.com"
}
}" \
--user 'username':'password'
Success response:
{
"result": {
"status": "Success",
"sysId: "533020eb879e85100f71cbfc0ebb3591"
}
}Example: Sample cURL request for test
curl "https://instance.service-now.com/api/sn_devops/devops/tool/test?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"attemptNumber": 1,
"blockedTests": 0,
"buildNumber": 675,
"duration": 0.079,
"failedTests": 0,
"finishTime": "2022-03-23T12:02:25.957Z",
"name": "adoTests/DeployableRepo/Test #675-2982",
"passedTests": 20,
"pipelineName": "adoTests/DeployableRepo",
"skippedTests": 0,
"stageName": "Test",
"startTime": "2022-03-23T12:02:24.36Z",
"taskExecutionUrl": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=675#Test/{Job name}",
"totalTests": 20,
"url": "https://dev.azure.com/xyzabcd/adoTests/_TestManagement/Runs?runId=2982&_a=runCharts"
}" \
--user 'username':'password'
Success response:
{
"result": {
"status": "Success",
"sysId: "fd3fdc6b879e85100f71cbfc0ebb356a"
}
}DevOps - POST /devops/tool/event/{sn_tool_id}
Posts the passed in payload from GitHub, Jira, or Bitbucket to the Events [sn_devops_event] table for processing by a pre-built subflow.
To process events from any other tool besides GitHub, Jira, or Bitbucket, use the DevOps - POST /devops/tool/{capability} endpoint instead.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/tool/event/{sn_tool_id}
Default URL: /api/sn_devops/devops/tool/event/{sn_tool_id}
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| sn_tool_id | Sys_id of the tool to use for the request. Data type: String Table: Devops Tools [sn_devops_tool] |
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| Tool dependent | The tool determines the content of the payload. The payload can be located in the tool under the webhook information. |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 201 | Request completed successfully. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Invalid or missing authentication. |
| 500 | Internal Server Error. A logic error on the server-side code occurred. |
Response body parameters
| Name | Description |
|---|---|
| result | Response status. Possible values:
Data type: String |
Example: cURL request
GitHub
curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/46a07b2f471e011028c23a34846d43b2" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"ref": "refs/heads/master",
"before": "59078a17cad1f4129754971c808d6c399b6141a5",
"after": "b7957bab20835449c4d597fee24075a9a5a2c099",
"repository": {
"id": 252146476,
"node_id": "MDEwOlJlcG9zaXRvcnkyNTIxNDY0NzY=",
"name": "test",
"full_name": "Xyz002/test",
"private": false,
"owner": {
"name": "Xyz002",
"email": "62993516+Xyz002@users.noreply.github.com",
"login": "Xyz002",
"id": 62993516,
"node_id": "MDQ6VXNlcjYyOTkzNTE2",
"avatar_url": "https://avatars.githubusercontent.com/u/62993516?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/Xyz002",
"html_url": "https://github.com/Xyz002",
"followers_url": "https://api.github.com/users/Xyz002/followers",
"following_url": "https://api.github.com/users/Xyz002/following{/other_user}",
"gists_url": "https://api.github.com/users/Xyz002/gists{/gist_id}",
"starred_url": "https://api.github.com/users/Xyz002/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/Xyz002/subscriptions",
"organizations_url": "https://api.github.com/users/Xyz002/orgs",
"repos_url": "https://api.github.com/users/Xyz002/repos",
"events_url": "https://api.github.com/users/Xyz002/events{/privacy}",
"received_events_url": "https://api.github.com/users/Xyz002/received_events",
"type": "User",
"site_admin": false
},
"html_url": "https://github.com/Xyz002/test",
"description": null,
"fork": false,
"url": "https://github.com/Xyz002/test",
"forks_url": "https://api.github.com/repos/Xyz002/test/forks",
"keys_url": "https://api.github.com/repos/Xyz002/test/keys{/key_id}",
"collaborators_url": "https://api.github.com/repos/Xyz002/test/collaborators{/collaborator}",
"teams_url": "https://api.github.com/repos/Xyz002/test/teams",
"hooks_url": "https://api.github.com/repos/Xyz002/test/hooks",
"issue_events_url": "https://api.github.com/repos/Xyz002/test/issues/events{/number}",
"events_url": "https://api.github.com/repos/Xyz002/test/events",
"assignees_url": "https://api.github.com/repos/Xyz002/test/assignees{/user}",
"branches_url": "https://api.github.com/repos/Xyz002/test/branches{/branch}",
"tags_url": "https://api.github.com/repos/Xyz002/test/tags",
"blobs_url": "https://api.github.com/repos/Xyz002/test/git/blobs{/sha}",
"git_tags_url": "https://api.github.com/repos/Xyz002/test/git/tags{/sha}",
"git_refs_url": "https://api.github.com/repos/Xyz002/test/git/refs{/sha}",
"trees_url": "https://api.github.com/repos/Xyz002/test/git/trees{/sha}",
"statuses_url": "https://api.github.com/repos/Xyz002/test/statuses/{sha}",
"languages_url": "https://api.github.com/repos/Xyz002/test/languages",
"stargazers_url": "https://api.github.com/repos/Xyz002/test/stargazers",
"contributors_url": "https://api.github.com/repos/Xyz002/test/contributors",
"subscribers_url": "https://api.github.com/repos/Xyz002/test/subscribers",
"subscription_url": "https://api.github.com/repos/Xyz002/test/subscription",
"commits_url": "https://api.github.com/repos/Xyz002/test/commits{/sha}",
"git_commits_url": "https://api.github.com/repos/Xyz002/test/git/commits{/sha}",
"comments_url": "https://api.github.com/repos/Xyz002/test/comments{/number}",
"issue_comment_url": "https://api.github.com/repos/Xyz002/test/issues/comments{/number}",
"contents_url": "https://api.github.com/repos/Xyz002/test/contents/{+path}",
"compare_url": "https://api.github.com/repos/Xyz002/test/compare/{base}...{head}",
"merges_url": "https://api.github.com/repos/Xyz002/test/merges",
"archive_url": "https://api.github.com/repos/Xyz002/test/{archive_format}{/ref}",
"downloads_url": "https://api.github.com/repos/Xyz002/test/downloads",
"issues_url": "https://api.github.com/repos/Xyz002/test/issues{/number}",
"pulls_url": "https://api.github.com/repos/Xyz002/test/pulls{/number}",
"milestones_url": "https://api.github.com/repos/Xyz002/test/milestones{/number}",
"notifications_url": "https://api.github.com/repos/Xyz002/test/notifications{?since,all,participating}",
"labels_url": "https://api.github.com/repos/Xyz002/test/labels{/name}",
"releases_url": "https://api.github.com/repos/Xyz002/test/releases{/id}",
"deployments_url": "https://api.github.com/repos/Xyz002/test/deployments",
"created_at": 1585737871,
"updated_at": "2022-01-04T14:37:36Z",
"pushed_at": 1648103939,
"git_url": "git://github.com/Xyz002/test.git",
"ssh_url": "git@github.com:Xyz002/test.git",
"clone_url": "https://github.com/Xyz002/test.git",
"svn_url": "https://github.com/Xyz002/test",
"homepage": null,
"size": 1378,
"stargazers_count": 0,
"watchers_count": 0,
"language": "Java",
"has_issues": true,
"has_projects": true,
"has_downloads": true,
"has_wiki": true,
"has_pages": false,
"forks_count": 0,
"mirror_url": null,
"archived": false,
"disabled": false,
"open_issues_count": 2,
"license": null,
"allow_forking": true,
"is_template": false,
"topics": [],
"visibility": "public",
"forks": 0,
"open_issues": 2,
"watchers": 0,
"default_branch": "master",
"stargazers": 0,
"master_branch": "master"
},
"pusher": {
"name": "Xyz002",
"email": "62993516+Xyz002@users.noreply.github.com"
},
"sender": {
"login": "Xyz002",
"id": 62993516,
"node_id": "MDQ6VXNlcjYyOTkzNTE2",
"avatar_url": "https://avatars.githubusercontent.com/u/62993516?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/Xyz002",
"html_url": "https://github.com/Xyz002",
"followers_url": "https://api.github.com/users/Xyz002/followers",
"following_url": "https://api.github.com/users/Xyz002/following{/other_user}",
"gists_url": "https://api.github.com/users/Xyz002/gists{/gist_id}",
"starred_url": "https://api.github.com/users/Xyz002/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/Xyz002/subscriptions",
"organizations_url": "https://api.github.com/users/Xyz002/orgs",
"repos_url": "https://api.github.com/users/Xyz002/repos",
"events_url": "https://api.github.com/users/Xyz002/events{/privacy}",
"received_events_url": "https://api.github.com/users/Xyz002/received_events",
"type": "User",
"site_admin": false
},
"created": false,
"deleted": false,
"forced": false,
"base_ref": null,
"compare": "https://github.com/Xyz002/test/compare/59078a17cad1...b7957bab2083",
"commits": [
{
"id": "b7957bab20835449c4d597fee24075a9a5a2c099",
"tree_id": "fa8d699762ec0a25868fa1ab4d299da392f0a974",
"distinct": true,
"message": "updated this file",
"timestamp": "2022-03-24T12:08:59+05:30",
"url": "https://github.com/Xyz002/test/commit/b7957bab20835449c4d597fee24075a9a5a2c099",
"author": {
"name": "Xyz002",
"email": "62993516+Xyz002@users.noreply.github.com",
"username": "Xyz002"
},
"committer": {
"name": "GitHub",
"email": "noreply@github.com",
"username": "web-flow"
},
"added": [],
"removed": [],
"modified": [
"README.me"
]
}
],
"head_commit": {
"id": "b7957bab20835449c4d597fee24075a9a5a2c099",
"tree_id": "fa8d699762ec0a25868fa1ab4d299da392f0a974",
"distinct": true,
"message": "updated this file",
"timestamp": "2022-03-24T12:08:59+05:30",
"url": "https://github.com/Xyz002/test/commit/b7957bab20835449c4d597fee24075a9a5a2c099",
"author": {
"name": "Xyz002",
"email": "62993516+Xyz002@users.noreply.github.com",
"username": "Xyz002"
},
"committer": {
"name": "GitHub",
"email": "noreply@github.com",
"username": "web-flow"
},
"added": [],
"removed": [],
"modified": [
"README.me"
]
},
"sn_tool_id": "46a07b2f471e011028c23a34846d43b2"
}" \
--user 'username':'password'
Success response:
{
"result": "success"
}Example: cURL request
Jira
curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/9ed237af471e011028c23a34846d4327" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"timestamp": 1648104684180,
"webhookEvent": "jira:issue_created",
"issue_event_type_name": "issue_created",
"user": {
"self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
"name": "admin",
"key": "admin",
"emailAddress": "username@email.com",
"avatarUrls": {
"48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
"24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
"16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
"32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
},
"displayName": "Administrator",
"active": true,
"timeZone": "America/Los_Angeles"
},
"issue": {
"id": "84800",
"self": "http://jira1.sndevops.xyz/rest/api/2/issue/84800",
"key": "BAL-2",
"fields": {
"issuetype": {
"self": "http://jira1.sndevops.xyz/rest/api/2/issuetype/10002",
"id": "10002",
"description": "A task that needs to be done.",
"iconUrl": "http://jira1.sndevops.xyz/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype",
"name": "Task",
"subtask": false,
"avatarId": 10318
},
"timespent": null,
"project": {
"self": "http://jira1.sndevops.xyz/rest/api/2/project/10507",
"id": "10507",
"key": "BAL",
"name": "balu_devops",
"projectTypeKey": "software",
"avatarUrls": {
"48x48": "http://jira1.sndevops.xyz/secure/projectavatar?avatarId=10324",
"24x24": "http://jira1.sndevops.xyz/secure/projectavatar?size=small&avatarId=10324",
"16x16": "http://jira1.sndevops.xyz/secure/projectavatar?size=xsmall&avatarId=10324",
"32x32": "http://jira1.sndevops.xyz/secure/projectavatar?size=medium&avatarId=10324"
}
},
"fixVersions": [],
"aggregatetimespent": null,
"resolution": null,
"customfield_10302": null,
"customfield_10105": null,
"resolutiondate": null,
"workratio": 0,
"lastViewed": null,
"watches": {
"self": "http://jira1.sndevops.xyz/rest/api/2/issue/BAL-2/watchers",
"watchCount": 0,
"isWatching": false
},
"created": "2022-03-24T06:51:22.896+0000",
"priority": {
"self": "http://jira1.sndevops.xyz/rest/api/2/priority/3",
"iconUrl": "http://jira1.sndevops.xyz/images/icons/priorities/medium.svg",
"name": "Medium",
"id": "3"
},
"customfield_10100": "0|i0cprw:",
"customfield_10101": "SCRUMBOARD-14",
"customfield_10300": null,
"labels": [],
"timeestimate": 240,
"aggregatetimeoriginalestimate": 300,
"versions": [],
"issuelinks": [
{
"id": "10701",
"self": "http://jira1.sndevops.xyz/rest/api/2/issueLink/10701",
"type": {
"id": "10000",
"name": "Blocks",
"inward": "is blocked by",
"outward": "blocks",
"self": "http://jira1.sndevops.xyz/rest/api/2/issueLinkType/10000"
},
"outwardIssue": {
"id": "84741",
"key": "BAL-1",
"self": "http://jira1.sndevops.xyz/rest/api/2/issue/84741",
"fields": {
"summary": "log4jtesting",
"status": {
"self": "http://jira1.sndevops.xyz/rest/api/2/status/3",
"description": "This issue is being actively worked on at the moment by the assignee.",
"iconUrl": "http://jira1.sndevops.xyz/images/icons/statuses/inprogress.png",
"name": "In Progress",
"id": "3",
"statusCategory": {
"self": "http://jira1.sndevops.xyz/rest/api/2/statuscategory/4",
"id": 4,
"key": "indeterminate",
"colorName": "yellow",
"name": "In Progress"
}
},
"priority": {
"self": "http://jira1.sndevops.xyz/rest/api/2/priority/3",
"iconUrl": "http://jira1.sndevops.xyz/images/icons/priorities/medium.svg",
"name": "Medium",
"id": "3"
},
"issuetype": {
"self": "http://jira1.sndevops.xyz/rest/api/2/issuetype/10004",
"id": "10004",
"description": "A problem which impairs or prevents the functions of the product.",
"iconUrl": "http://jira1.sndevops.xyz/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype",
"name": "Bug",
"subtask": false,
"avatarId": 10303
}
}
}
}
],
"assignee": {
"self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
"name": "admin",
"key": "admin",
"emailAddress": "username@email.com",
"avatarUrls": {
"48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
"24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
"16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
"32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
},
"displayName": "Administrator",
"active": true,
"timeZone": "America/Los_Angeles"
},
"updated": "2022-03-24T06:51:22.896+0000",
"status": {
"self": "http://jira1.sndevops.xyz/rest/api/2/status/10000",
"description": "",
"iconUrl": "http://jira1.sndevops.xyz/",
"name": "To Do",
"id": "10000",
"statusCategory": {
"self": "http://jira1.sndevops.xyz/rest/api/2/statuscategory/2",
"id": 2,
"key": "new",
"colorName": "blue-gray",
"name": "To Do"
}
},
"components": [],
"timeoriginalestimate": 300,
"description": "Task description",
"timetracking": {
"originalEstimate": "5m",
"remainingEstimate": "4m",
"originalEstimateSeconds": 300,
"remainingEstimateSeconds": 240
},
"customfield_10203": null,
"customfield_10204": null,
"customfield_10205": null,
"attachment": [],
"aggregatetimeestimate": 240,
"summary": "Task Summary",
"creator": {
"self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
"name": "admin",
"key": "admin",
"emailAddress": "username@email.com",
"avatarUrls": {
"48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
"24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
"16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
"32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
},
"displayName": "Administrator",
"active": true,
"timeZone": "America/Los_Angeles"
},
"subtasks": [],
"reporter": {
"self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
"name": "admin",
"key": "admin",
"emailAddress": "username@email.com",
"avatarUrls": {
"48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
"24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
"16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
"32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
},
"displayName": "Administrator",
"active": true,
"timeZone": "America/Los_Angeles"
},
"customfield_10000": "{summaryBean=com.atlassian.jira.plugin.devstatus.rest.SummaryBean@2ccf8c6[summary={pullrequest=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@fbc42d4[overall=PullRequestOverallBean{stateCount=0, state='OPEN', details=PullRequestOverallDetails{openCount=0, mergedCount=0, declinedCount=0}},byInstanceType={}], build=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@71e33347[overall=com.atlassian.jira.plugin.devstatus.summary.beans.BuildOverallBean@1c24654d[failedBuildCount=0,successfulBuildCount=0,unknownBuildCount=0,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], review=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@1ea8fb17[overall=com.atlassian.jira.plugin.devstatus.summary.beans.ReviewsOverallBean@6dc95939[stateCount=0,state=<null>,dueDate=<null>,overDue=false,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], deployment-environment=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@55826cc[overall=com.atlassian.jira.plugin.devstatus.summary.beans.DeploymentOverallBean@3ae93527[topEnvironments=[],showProjects=false,successfulCount=0,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], repository=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@6340012e[overall=com.atlassian.jira.plugin.devstatus.summary.beans.CommitOverallBean@44678cee[count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], branch=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@4dbce8[overall=com.atlassian.jira.plugin.devstatus.summary.beans.BranchOverallBean@737ee1cb[count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}]},errors=[],configErrors=[]], devSummaryJson={\"cachedValue\":{\"errors\":[],\"configErrors\":[],\"summary\":{\"pullrequest\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"stateCount\":0,\"state\":\"OPEN\",\"details\":{\"openCount\":0,\"mergedCount\":0,\"declinedCount\":0,\"total\":0},\"open\":true},\"byInstanceType\":{}},\"build\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"failedBuildCount\":0,\"successfulBuildCount\":0,\"unknownBuildCount\":0},\"byInstanceType\":{}},\"review\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"stateCount\":0,\"state\":null,\"dueDate\":null,\"overDue\":false,\"completed\":false},\"byInstanceType\":{}},\"deployment-environment\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"topEnvironments\":[],\"showProjects\":false,\"successfulCount\":0},\"byInstanceType\":{}},\"repository\":{\"overall\":{\"count\":0,\"lastUpdated\":null},\"byInstanceType\":{}},\"branch\":{\"overall\":{\"count\":0,\"lastUpdated\":null},\"byInstanceType\":{}}}},\"isStale\":false}}",
"aggregateprogress": {
"progress": 0,
"total": 240,
"percent": 0
},
"customfield_10200": null,
"customfield_10201": null,
"customfield_10202": null,
"environment": null,
"duedate": "2022-03-24",
"progress": {
"progress": 0,
"total": 240,
"percent": 0
},
"comment": {
"comments": [],
"maxResults": 0,
"total": 0,
"startAt": 0
},
"votes": {
"self": "http://jira1.sndevops.xyz/rest/api/2/issue/BAL-2/votes",
"votes": 0,
"hasVoted": false
},
"worklog": {
"startAt": 0,
"maxResults": 20,
"total": 0,
"worklogs": []
}
}
},
"changelog": {
"id": "14401",
"items": [
{
"field": "Link",
"fieldtype": "jira",
"from": null,
"fromString": null,
"to": "BAL-1",
"toString": "This issue blocks BAL-1"
}
]
},
"sn_tool_id": "9ed237af471e011028c23a34846d4327"
}" \
--user 'username':'password'
Success response:
{
"result": "success"
}Example: cURL request
Bitbucket
curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/6975ecaf879e85100f71cbfc0ebb3575" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"eventKey": "repo:refs_changed",
"date": "2022-03-23T15:57:05+0000",
"actor": {
"name": "admin",
"emailAddress": "username@email.com",
"id": 1,
"displayName": "Admin",
"active": true,
"slug": "admin",
"type": "NORMAL",
"links": {
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/users/admin"
}
]
}
},
"repository": {
"slug": "testautomationrepo1",
"id": 12,
"name": "TestAutomationRepo1",
"scmId": "git",
"state": "AVAILABLE",
"statusMessage": "Available",
"forkable": true,
"origin": {
"slug": "testautomationrepo1",
"id": 1,
"name": "TestAutomationRepo1",
"scmId": "git",
"state": "AVAILABLE",
"statusMessage": "Available",
"forkable": true,
"project": {
"key": "TES",
"id": 1,
"name": "TestAutomation",
"public": false,
"type": "NORMAL",
"links": {
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/projects/TES"
}
]
}
},
"public": false,
"links": {
"clone": [
{
"href": "ssh://git@bitbucket2.sndevops.xyz:7999/tes/testautomationrepo1.git",
"name": "ssh"
},
{
"href": "http://bitbucket2.sndevops.xyz/scm/tes/testautomationrepo1.git",
"name": "http"
}
],
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/projects/TES/repos/testautomationrepo1/browse"
}
]
}
},
"project": {
"key": "~ADMIN",
"id": 3,
"name": "Admin",
"type": "PERSONAL",
"owner": {
"name": "admin",
"emailAddress": "username@email.com",
"id": 1,
"displayName": "Admin",
"active": true,
"slug": "admin",
"type": "NORMAL",
"links": {
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/users/admin"
}
]
}
},
"links": {
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/users/admin"
}
]
}
},
"public": false,
"links": {
"clone": [
{
"href": "http://bitbucket2.sndevops.xyz/scm/~admin/testautomationrepo1.git",
"name": "http"
},
{
"href": "ssh://git@bitbucket2.sndevops.xyz:7999/~admin/testautomationrepo1.git",
"name": "ssh"
}
],
"self": [
{
"href": "http://bitbucket2.sndevops.xyz/users/admin/repos/testautomationrepo1/browse"
}
]
}
},
"changes": [
{
"ref": {
"id": "refs/heads/master",
"displayId": "master",
"type": "BRANCH"
},
"refId": "refs/heads/master",
"fromHash": "b482b2e232f5fbdee73feed8ca1cfb774de6976e",
"toHash": "d783254fe6f77bc7cc079358158aeef52a457587",
"type": "UPDATE"
}
],
"sn_tool_id": "6975ecaf879e85100f71cbfc0ebb3575"
}" \
--user 'username':'password'
Success response:
{
"result": "success"
}DevOps - PUT /devops/orchestration/changeControl/{changeControlId}
Updates the change control information for the specified orchestration task.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/changeControl/{changeControlId}
Default URL: /api/sn_devops/devops/orchestration/changeControl/{changeControlId}
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| changeControlId | Sys_id of the change control task.
Located in the Callback [sn_devops_callback] table.
Data type: String |
| Name | Description |
|---|---|
| toolId | Required. Sys_id of the DevOps tool associated with the change control task. Data type: String Table: Orchestration Tool [sn_devops_orchestration_tool] |
| Name | Description |
|---|---|
| callbackURL | Required. URL that the ServiceNow instance can call back once the
associated change request approval process is complete. This callback should let the
pipeline execution continue or not, based on the approval result.
Data type: String |
| orchestrationTaskDetails | Required. Description of the orchestration task.
Data type: Object |
| orchestrationTaskDetails.message | Free-form text
message.
Data type: String |
| orchestrationTaskDetails.triggerType | Required. The way the orchestration task was started.
Valid values:
Data type: String |
| orchestrationTaskDetails.upstreamTaskExecutionURL | Required if triggerType is set to upstream. Upstream task execution URL.
For example: https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/ Data type: String |
| orchestrationTaskURL | Required. URL of the orchestration task.
For example: https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ Data type: String |
| toolType | Type of DevOps tool. Valid value: jenkins Data type: String |
| taskExecutionURL | Required. URL of the task to execute. Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Request completed successfully. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Invalid or missing authentication. |
| 404 | Not Found. The specified record couldn't be found. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters
| Name | Description |
|---|---|
| change_control | Flag that indicates whether the orchestration task is under change control. Possible values:
Data type: Boolean |
| details | Entry for all error conditions.
Data type: Object |
| details.errors | Description of a single error.
Data type: Array of Objects |
| details.errors.message | Detailed error message.
Data type: String |
Example: Sample cURL request
curl -X PUT "https://instance.service-now.com/api/sn_devops/v1/devops/orchestration/changeControl/f0ca45679323008b52f3b457415ae6?toolId=f0ca45679323008b52f3b457415ae6"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
\"orchestrationTaskURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-deploy/\",
\"toolType\":\"jenkins\",
\"callbackURL\":\"https://jenkins.mycompany.com:8080/sn-devops/964aca59-0cae-4d9b-a36d-5929f426cf31\",
\"taskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\",
"\orchestrationTaskName\":\"StageName\",
\"orchestrationTaskDetails\":{
\"message\":\"Started by upstream project \\\"Mobile-Platform-test\\\" build number 40\",
\"triggerType\":\"upstream\",
\"upstreamTaskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\"}
}"Response:
{
"result": {
"change_control": true
}
}DevOps - PUT /devops/orchestration/changeInfo/{changeInfo}
Updates fields in a specified change request.
URL format
Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/changeInfo/{changeInfo}
Default URL: /api/sn_devops/devops/orchestration/changeInfo/{changeInfo}
Supported request parameters
| Name | Description |
|---|---|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the
latest.
Data type: String |
| Name | Description |
|---|---|
| changeRequestNumber | Required. Change request number associated with the orchestration task to update. Data type: String Table: Change Request [change_request] |
| Name | Description |
|---|---|
| data | Required. Name-value pairs for the field(s) to update in the associated change
request. For example, to update the short description file, enter a name-value
pair similar to the
following: For
the state parameter, only the following transitions are supported:
Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Authorization | Starting with v2, this API supports token-based authentication. Tokens can be acquired by clicking the Copy token button on the tool record, located in the Tool
[sn_devops_tool] table. The token can then be used in an authorization header in the format Authorization: sn_devops.DevOpsToken <tool_sys_id>:<tool_token>.Note: If Basic Auth details (user name and password) are provided in addition to an authorization header with token, Basic Auth takes precedence. If the devops.system user is not available in your instance, use the Switch to this user after token based authentication is successful property. This property enables setting any user that has the sn_devops.integration role, which is needed to complete the token authentication. For information, see DevOps Change Velocity properties. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 404 | Not found. The requested item wasn't found. |
Response body parameters
| Name | Description |
|---|---|
| message | Description of the results of the update. Data type: String |
| status | Status of the request. Possible values:
Data type: String |
| updateStatus | Status of the update. Possible values:
Data type: String |
Example: cURL request
The following code example shows how to update various fields in the CHG0030023 change request.
curl -X PUT"
https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeInfo?changeRequestNumber=CHG0030023
-H "accept: application/json"\
-u "username":"password"
- D
{
"short_description": "Test description",
"priority": "1",
"start_date": "2021-02-05 08:00:00",
"end_date": "2022-04-05 08:00:00",
"justification": "test justification",
"description": "test description",
"cab_required": true,
"comments": "This update for work notes is from jenkins file",
"work_notes": "test work notes",
"assignment_group": "a715cd759f2002002920bde8132e7018"
}Response:
{
"result": {
"updateStatus": "Done",
"status": "Success",
"message": "change request update successful"
}
}