ReleaseOwl Callout Framework

Callout is a feature of making a call to an external web service or sending an HTTP request and receiving the response. Each REST callout request is associated with an HTTP method and an endpoint. A REST API callout is the process of a client application submitting a request to an API and that API retrieving the requested data from the third-party system say external server or program and delivering it back to the client.

Note: Currently, we support callouts for only ServiceNow.

Registering Callout

This section is for registering REST API Callouts for ServiceNow.

1. In Administration, go to Callouts.

2. In page displayed, click Register Callout.

3. Fill in the required details.

Name	Enter any name of your choice for the callout being registered.
System Type	ServiceNow for ServiceNow API calling and Others for any generic REST/HTTP URL call
Credential	Select the Basic Auth credential that you have registered in the credential Manager.
URL Path	It specifies the address where the service is located. In case of ServiceNow, Instance Base URL will be populated automatically from the ServiceNow credential. User must enter the path for the required REST API.
HTTP Method	HTTP request like GET, POST, PUT, and DELETE. GET - It helps in retrieving resources identified by the URL PUT - It allows to update or replace the resource sent to the request body. POST - It creates a resource or post data to the server. DELETE - It deletes the resource identified by the URL Select the option based on the type of the REST API that is being called out.
Payload JSON	Payload JSON string is for POST and PUT types of requests that are passed from ReleaseOwl to the third-party system. Payload supports the parameters, which can be replaced in the Release Pipeline execution with values configured during Release Pipeline creation. Parameters are specified with enclosed double curly braces. For ex: {{}}
Response JSON	The response JSON string upon calling the third-party REST API.
Unique Identifier	Unique ID created by the third-party system for a particular REST API call in case of POST type request. This will be useful to track the tasks when callouts are used in the Release Pipeline. The expression specified in the field will be evaluated on the response JSON from the REST API call.

4. You can check whether the established connection to the third-party REST API is successful or not by clicking the Test button.

5. Once the connection is verified, you can save the callout.

Adding a Callout Task in Release Pipeline

You can add callout as a Task in the Release Pipeline.

1. When adding a new task in Pipeline stage, select Callout Task, then the following screen is displayed:

2. Fill in the required details:

Name	Enter any name of your choice for the callout task being created.
Callouts	Choose the required callout from the drop down.
Config Params	Parameters specified in the Payload JSON can be passed during run-time through the Config Params option.
Pipeline Execution	Continue on Failure – If selected, the Release Pipeline Execution will continue even if the callout fails. If the option is left unchecked, then the pipeline execution fails if it encounters any error in calling out the external API. Wait on Task – If selected, then approval task will be created after the callout execution even if callout fails or succeeds. Users can open the task and retry callout execution in case of callout failure. If the option is left unchecked, it will act as a normal web service call which calls out external API and continues based on the response of the external API.
Assign To	User – The approver (user) can be selected from the available list of users for approving the pending task in order to complete the Release Pipeline execution when Wait on Task option is chosen. Role - The pending task can be approved by any user with the user role that is selected in order to complete the Release Pipeline execution when Wait on Task option is chosen.
Message	Any message that is to be conveyed to the task approver can be mentioned here.

3. On clicking the Config Params button, the following screen is displayed. Enter the variable parameter names specified in the Payload JSON along with their values that are to be passed run-time during the execution of the Release Pipeline and save the changes.

System Defined Parameters

System Defined Parameters for a Callout Task - Generic

Below are the variables available for using as values in the configure parameters for a callout Task.

${jobins.jobCycleName}	Cycle name given while triggering the Release Pipeline.
${jobins.instantiatedBy}	Email ID of the person who triggered the Release Pipeline
${jobins.label}	Release Pipeline Name
${jobins.status}	Status of the instance/cycle/>
${jobins.endTime}	End time when instance is completed. (YYYY-MM-DDTHH24:MM:SS.000+0000)
${jobins.createTime}	Represents the time when instance was created. (YYYY-MM-DDTHH24:MM:SS.000+0000)
${jobins.startTime}	Represents the time when instance was started (YYYY-MM-DDTHH24:MM:SS.000+0000)

System Defined Parameters specific to the Release Pipelines of type SAP BTP

${jobins.inputs.buildJobName}	Name of the build pipeline used as an input for the Release Pipeline.
${jobins.inputs.buildNumber}	Build number of the build pipeline (given as input in the Release pipeline), artifact is used for deploying in the Release Pipeline.