Make a GET call

Overview

DOH is commonly used to create, delete, and update data through API calls, using the POST, DELETE, and PUT HTTP methods. The GET endpoints have also been supported, but previously, the response from a GET call could only be logged and stored in the UA_RUN_SERVICE_TRACE table when tracing was enabled. The response payload could not be processed or used for further actions.

The GET responses can now be passed to a Groovy handleResponse method. For more information about using handleResponse to process custom responses, see handle response executable and Mapping custom payloads.

A GET request does not include a request body but a service schema definition is still required so that a target mapping sequence can be created for the GET call.

Service

The following service definition is sufficient for a GET request.

A <root> element is required in the schema, but the element name can be any valid name. The payload attribute defines the default value for the @payload field mapping when a new target is created for the service.

For a GET request, where no request body is required, the payload value is defaulted to null.

The value in the Service URL field is appended to the serverUrl value configured on the task or executable. The URL Path defined on the target is then appended to create the complete API URL.

Source

Although a GET request does not send a request payload, a source Id is still required to determine the data that drives each GET call.

For example, if a GET call needs to be executed for every PERSON_ID in the CX_ABC_PERSON table, the source can be defined as a query that selects the required IDs.

The selected source columns can then be used to build the URL Path and are also available to the handleResponse Groovy method for additional processing.

Target

When a target is created, the service schema is used to generate the default Mapping Details.

For GET requests, this is usually the expected behavior because no request body is needed. When the mapping expression is null:

• The Content-Length header is set to 0.
• No request body is sent with the API call.

The following target settings are required:

• HTTP Method — Set to GET.
• Source Id — Specify the query or table that provides the data for each GET request.
• URL Path — Use source column values to build the API endpoint. For example, PERSON_ID can be added to the URL.

The @payload mapping is automatically created based on the payload attributes in the service schema. By default, the mapping expression is set to null.

The source column values are also available in the Groovy handleResponse method.

Task

The final step is to define a task that can be added to a chain and executed.

The task specifies the targets used to invoke the API and can optionally include a data block containing Groovy code to process API responses.

handleResponse Groovy Method

A task data block or executable code block can define a Groovy handleResponse method to process the response returned from an API call.

The method must accept a ServiceAPIResult parameter, which contains the API call results.

The default method name is handleResponse. This name can be overridden for a specific Mapping Sequence by using the @responseHandler field mapping. For an example, see Mapping custom payloads.

The method can return a value when results needs to be stored. This is intended for cross-reference scenarios where an API creates a new identifier that must be associated with a legacy value, such as when ORMBS assigns a new ACCT_ID.

Defining the Groovy Code

Groovy code can be defined in a task data block or executable code bloc.

Define in the task data block when the response handling logic is specific to a particular task and its targets.

When defined in a task data block, the Groovy code must be provided as the value of the groovy parameter:

groovy =
def handleResponse(ServiceAPIResult result) {
    ...
   return null
}

Define in the executable code block when the response handling logic should be reused across multiple tasks and targets.

The SERVICE_CALL executable can be duplicated, and the duplicated one can be modified to have the following code block. The tasks that need to invoke this method can then simply use this custom executable rather than the standard SERVICE_CALL one.

When defined in an Executable Code Block, only the Groovy method itself is required:

def handleResponse(ServiceAPIResult result) {
    ...
    return null
}

The ServiceAPIResult object provides the following getter methods:

getTaskWorkEntry()

The getTaskWorkEntry() method returns a ServiceWorkEntry object. This object contains the column values selected by the target mapping source.

The values can be accessed using the getColumnValue(String columnName) method.

def handleResponse(ServiceAPIResult result) {
    String personId = result.getTaskWorkEntry().getColumnValue('PERSON_ID')
    // Process personId
}

getHttpResponse()

The getHttpResponse() method returns a GenericHttpResponse object containing the API response body and headers.

The following example retrieves the response body, parses JSON content using JsonSlurper, and retrieves a response header:

def handleResponse(ServiceAPIResult result) {
    // Log the result object (for testing/troubleshooting only)
    CommonEnv.logInfo(result.toString())

    // Parse JSON response body
    def jsonSlurper = new groovy.json.JsonSlurper()
    def jsonObj = jsonSlurper.parseText(result.getHttpResponse().getBody())

    jsonObj.each { perNode ->
        CommonEnv.logInfo(perNode.toString())
    }

    // Retrieve response header value
    List<String> headerValues = result.getHttpResponse().getHeaderValue('ETag')
    CommonEnv.logInfo(headerValues.get(0))

    return null
}