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.

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.

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.

Note: This endpoint only returns the request body elements that are required.

URL format

Versioned URL: /api/sn_devops/{api_version}/devops/code/schema

Default URL: /api/sn_devops/devops/code/schema

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path 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
Table 2. Query parameters
Name Description
resource Required. Type of resource schema to return.

Valid values (not case-sensitive):

  • branch
  • commit
  • repository

Data type: String
Table 3. Request body parameters (XML or JSON)
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.

Table 4. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 5. Response headers
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.

Table 6. Status 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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 7. Path 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
Table 8. Query parameters
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
Table 9. Request body parameters
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.

Table 10. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 11. Response headers
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.

Response body parameters

NameDescription
result Results of the onboarding request.
Data type: Object
"result": {
  "code": "String",
  "importRequestsSysIds": "[Array],
  "messageDetails": {Object],
  "onboardingRequestID": "String",
  "status": "String"
}
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
"messageDetails": {
  "apps": [Array],
  "pipelines": [Array],
  "plans": [Array],
  "repositories": [Array],
  "status": "String",
  "toolResponse": [Array]
}
result.messageDetails.apps Defines the apps to create within the associated ServiceNow instance.

Data type: Array of Objects

"apps": [{
  "appId": "String",
  "message": "String",
  "name": "String",
  "status": "String",
}]
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:
  • Failed
  • Partial Success
  • Success

Data type: String
result.messageDetails.pipelines List of pipelines associated with the onboarding event and their corresponding details.

Data type: Array of Objects

"pipelines": [{
  "changeStepAssociation": [Array],
  "errors": "String",
  "message": "String",
  "name": "String",
  "status": "String",
}]
result.messageDetails.pipelines.changeStepAssociation Array of objects that describe any change steps that are associated with the onboarding.

Data type: Array of Objects

"changeStepAssociation": [{
  "changeStepName": "String",
  "status": "String",
  "summary": "String",
}]
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:
  • Failed
  • Success

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

"plans": [{
  "errors": "String",
  "message": "String",
  "name": "String",
  "status": "String",
}]
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

"repositories": [{
  "configureStatus": {Object}, 
  "name": "String",
  "status": "String",
}]
result.messageDetails.repositories.configureStatus Details of the webhook configuration status for the repository.

Data type: Object

"configureStatus": {
  "message": "String",
  "status": "String",
}
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:
  • Failed
  • Partial Success
  • Success

Data type: String
result.messageDetails.toolResponse List of tools to onboard within the associated ServiceNow instance.

Data type: Array of Objects

"toolResponse": [{
  "configureStatus": {Object},
  "connectStatus": {Object},
  "createStatus": {Object},
  "discoveryStatus": {Object},
  "name": "String",
  "status": "String",
  "type": "String"
}]
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

"configureStatus": {
  "error": "String",
  "message": "String",
  "status": "String"
}
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

"connectStatus": {
  "error": "String",
  "message": "String",
  "status": "String"
}
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

"createStatus": {
  "error": "String",
  "message": "String",
  "status": "String"
}
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

"discoveryStatus": {
  "error": "String",
  "imports: [Array],
  "message": "String",
  "status": "String"
}
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

"imports": [{
  "details": "String",
  "id": "String",
  "status": "String"
}]
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:
  • Failed
  • Partial Success
  • Success

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 13. Path 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
Table 15. Request body parameters
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.

Table 16. Request 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.
Table 17. Response headers
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.

Table 18. Status 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:
  • true: Under change control.
  • false: Not under change control.

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 19. Path 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
Table 21. Request body parameters (XML or JSON)
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.

Table 22. Request 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.
Table 23. Response headers
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.

Table 24. Status 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)

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.

Note: This endpoint only returns the request body elements that are required.

URL format

Versioned URL: /api/sn_devops/{api_version}/devops/orchestration/schema

Default URL: /api/sn_devops/devops/orchestration/schema

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 25. Path 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
Table 26. Query parameters
Name Description
resource Type of resource schema to return.
Valid values (not case-sensitive):
  • build_details
  • callback
  • orchestration_task
  • task_execution

Data type: String
Table 27. Request body parameters
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.

Table 28. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 29. Response headers
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.

Table 30. Status 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

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 31. Path 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
Table 33. Request body parameters
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.

Table 34. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 35. Response headers
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.

Table 36. Status 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:
  • true: Verification was successful.
  • false: Verification wasn't successful.

Data type: Boolean
stepValid Flag that indicates whether the information sent is valid.
Valid values:
  • true: Information sent is valid.
  • false: Information sent isn't valid.

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.

Note: This endpoint only returns the request body elements that are required.

URL format

Versioned URL: /api/sn_devops/{api_version}/devops/plan/schema

Default URL: /api/sn_devops/devops/plan/schema

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 37. Path 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
Table 38. Query parameters
Name Description
resource Type of resource schema to return.

Valid values (not case-sensitive):

  • app
  • version
  • work_item

Data type: String
Table 39. Request body parameters
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.

Table 40. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 41. Response headers
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.

Response body parameters

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.

This endpoint creates new artifacts and artifact versions, and associates them to commits. The following describes the endpoint process flow:
  • 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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 43. Path 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
Table 44. Query parameters
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]

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.

Table 46. Request 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.
Table 47. Response headers
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.

Response body parameters

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.

This endpoint can perform the following actions:
  • 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.

Application onboarding matrix

URL format

Versioned URL: /api/sn_devops/{api_version}/devops/onboarding/app

Default URL: /api/sn_devops/devops/onboarding/app

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 49. Path 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
Table 50. Query parameters
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.

Table 52. Request 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.
Table 53. Response headers
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.

Table 54. Status codes
Status code Description
202 Onboarding request was successfully created.

Response body parameters

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.

Depending on the type of tool for which the request is posted, the endpoint performs the following actions:
  • 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)
All of these actions are tool specific and are executed based on the integration capabilities for the specified tool.

Tool onboarding matrix

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 55. Path 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
Table 56. Query parameters
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.

Table 58. Request 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.
Table 59. Response headers
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.

Table 60. Status codes
Status code Description
202 Onboarding request was successfully created.

Response body parameters

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 61. Path 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
Table 62. Query parameters
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

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.

Table 64. Request 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.
Table 65. Response headers
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.

Response body parameters

Name Description
changeControl Flag that indicates whether the orchestration task is under change control.
Possible values:
  • true: Under change control.
  • false: Not under change control.

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 67. Path 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
Table 68. Query parameters
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

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.

Table 70. Request 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.
Table 71. Response headers
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.

Response body parameters

Element Description
status Flag that indicates whether the verification was successful.
Valid values:
  • true: Verification was successful.
  • false: Verification wasn't successful.

Data type: Boolean
stepValid Flag that indicates whether the information sent is valid.
Valid values:
  • true: Information sent is valid.
  • false: Information sent isn't valid.

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.

Typically, you will pass in the artifacts.version and artifacts.name parameters when identifying an artifact version to include in a package. You can also use the advanced features of this endpoint which allows you to pass the build details for each artifact version instead of the version itself. Artifact-specific build details include the following parameters:
  • artifacts.pipelineName or artifacts.projectName
  • artifacts.taskExecutionNumber
  • artifacts.stageName
  • artifacts.branchName
The endpoint uses these artifact-specific build details to look up task execution information and then copies the associated versions to the package. It uses non-artifact specific build details (pipelineName or projectName, taskExecutionNumber, branchName, and stageName) to associate the created package to a pipeline execution.
Note: This endpoint does not support updates. It always creates a new package even if one with same name already exists.

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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 73. Path 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
Table 74. Query parameters
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]

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.

Table 76. Request 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.
Table 77. Response headers
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.

Response body parameters

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.

Note: Starting with 1.34.1 version, a new version of this API has been introduced. With this API, Adaptive Authentication policies may not execute as expected. For more information about these policies, see Adaptive authentication.

URL format

Versioned URL: /api/sn_devops/{api_version}/devops/tool/{capability}

Default URL: /api/sn_devops/devops/tool/{capability}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 79. Path 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):
  • artifact
  • code
  • orchestration
  • plan
  • test

Data type: String
Table 80. Query parameters
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
Table 81. Request body parameters
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.

Table 82. Request 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.
Table 83. Response headers
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.

Response body parameters

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.

Before calling this endpoint, you must create an integration with the tool you're using.

To process events from any other tool besides GitHub, Jira, or Bitbucket, use the DevOps - POST /devops/tool/{capability} endpoint instead.

Note: Starting with 1.34.1 version, a new version of this API has been introduced. With this API, Adaptive Authentication policies may not execute as expected. For more information about these policies, see Adaptive authentication.

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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 85. Path 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]
Table 86. Query parameters
Name Description
None
Table 87. Request body parameters
Name Description
Tool dependant 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.

Table 88. Request 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.
Table 89. Response headers
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.

Response body parameters

Name Description
result Response status.
Possible values:
  • failure: Incorrect tool ID. Event not created.
  • success: Event created in the Events [sn_devops_event] table. However, the event state may be Error if an incorrect payload was provided.

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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 91. Path 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
Table 92. Query parameters
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]

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.

Table 94. Request 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.
Table 95. Response headers
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.

Response body parameters

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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 97. Path 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
Table 98. Query parameters
Name Description
changeRequestNumber Required. Change request number associated with the orchestration task to update.

Data type: String

Table: Change Request [change_request]
Table 99. Request body parameters
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:
 "{\"short_description\": \"my short desc\" }"
For the state parameter, only the following transitions are supported:
  • cancel:
    • Change request state must be implemented to move the state to cancel.
    • The reason parameter is a mandatory input to update the state to canceled.
  • closed:
    • Change request state must be implement or post implement to move the state to close.
    • close_code and close_notes are mandatory input for updating the state to closed.
      Possible values:
      • 4: Cancel (Value set in the sn_devops.change_request.cancel_state property.)
      • 3: Closed (Value set in the sn_devops.change_request.closed_state property.)

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.

Table 100. Request 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.
Table 101. Response headers
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.

Table 102. Status 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:
  • Success: Change request was found and change details were updated successfully.
  • Error: Change request was not found and change details were not updated.

Data type: String
updateStatus Status of the update.
Possible values:
  • Done
  • Error

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"
  }
}