As a user of z/OSMF Workflows, you can design a workflow step that invokes a Representational State Transfer (REST) service. This step is referred to as a REST step. The REST steps can send REST requests, obtain values from the response, and assign the values to variables defined in the workflow.

This article introduces how to use REST steps in z/OSMF Workflow Editor and Workflows.

Use Workflow Editor to design REST step

You can use Workflow Editor to create a new REST step by choosing the “Step Type” as “REST API”.

On the Step Type tab of Workflow Editor, you can specify “HTTP method”, “URI path”, “User name”, “Password”, “Query parameters”, “Request Header”, “Request Body”, “Poll Attributes”, “Expected Status Code” and so on for a REST step. For detailed information, please refer to online help of Workflow Editor: https://www.ibm.com/docs/en/zos/3.1.0?topic=tab-rest-steps.

Perform the designed REST step in Workflows

After the REST step is created in Workflow Editor, the REST step can be saved in the workflow definition file. You can create a new workflow instance based on the workflow definition file and perform the designed REST step in Workflows.

The screen shot below illustrates the Workflow UI when you perform the REST step.

You can leverage the Status tab to check the results of a REST step. The “Expected status code” comes from the REST API request, as defined in the workflow definition. The “Actual status code” indicates the actual status code of the step. If this actual status code matches the expected one, the Workflows task marks the “State” of step as "Complete". The “Response” tab shows the contents of the response body.

The screen shot below illustrates a "Complete" workflow REST step.

Key functionalities of Workflow REST step

1.Connect to a system other than local system

To connect to a system other than the local system, you need to specify “scheme name”, “host name”, and the optional port number. Additionally, for a HTTPS connection, the “user name” and “password” to be used for logging in to the receiving system are needed.

Here is an example of listing workflows on a remote systems.

<rest>

    <httpMethod>GET</httpMethod>

    <schemeName>https</schemeName>

    <hostname substitution="true">${instance-otherSysHostname}</hostname>

    <port substitution="true">${instance-otherSysPort}</port>

    <uriPath substitution="false">/zosmf/workflow/rest/1.0/workflows/</uriPath>

    <expectedStatusCode>200</expectedStatusCode>

    <username substitution="true">${instance-otherSysUser}</username>

    <password substitution="true">${instance-PW}</password>

    <requestHeaders substitution="false">{"X-CSRF-ZOSMF-HEADER":"ZOSMF"}</requestHeaders>

</rest>

2.Run REST step several times

If you want to run the REST step several times until the task completes, you can use the loop function of REST step by adding the "pollCountMaximum", "pollWaitTime" and "pollExitCondition".

If the returned value in the response matches the expectedValue defined in the “pollExitCondition”, the poll exits and returns to the caller. Otherwise, polling continues for the specified poll count maximum. If no match is found within the specified polling limits, the REST step fails.

Below is an example to obtain the status of the job until the job status is “output”.

<rest>

    <httpMethod>GET</httpMethod>

    <uriPath substitution="true">/zosmf/restjobs/jobs/${instance-jobname}/${instance-jobid}</uriPath>

    <expectedStatusCode>200</expectedStatusCode>

    <propertyMapping mapTo="jobstatus">["status"]</propertyMapping>

    <pollCountMaximum substitution="false">10</pollCountMaximum>

    <pollWaitTime substitution="false">5</pollWaitTime>

    <pollExitCondition expectedValue="OUTPUT">status</pollExitCondition>

</rest>

3.Map the response data to variables in workflow

You can use “propertyMapping” to obtain values from the response and assign the values to variables defined in the workflow. To map different types of response body, user should specify different mapping syntax.

3.1.Map the JSONArray type response

For example, the response of “List the jobs” API is JSONArray type. You can use below syntax to get “job_correlator”, “jobname” and “jobid” of the first job from the response data and assign the values into workflow variables.

<rest>

    <httpMethod>GET</httpMethod>

    <uriPath substitution="true">/zosmf/restjobs/jobs</uriPath>

    <expectedStatusCode>200</expectedStatusCode>

    <propertyMapping mapTo="job_correlator">[0]["job-correlator"]</propertyMapping>

    <propertyMapping mapTo="jobid">[0]["jobid"]</propertyMapping>

    <propertyMapping mapTo="jobname">[0]["jobname"]</propertyMapping>

</rest>

3.2 Map the JSONObject type response

For example, the response of “List the workflows” API is JSONObject type. You can use below syntax to get “workflowKey” of the first workflow instance from the response data and assign the value into a workflow instance variable “workflowKey”.

<rest>

    <httpMethod>GET</httpMethod>

    <uriPath substitution="true">/zosmf/workflow/rest/1.0/workflows</uriPath>

    <expectedStatusCode>200</expectedStatusCode>

    <propertyMapping mapTo="workflowKey">["workflows"][0]["workflowKey"]</propertyMapping>

</rest>

3.3 Map the text type response

For example, the response of “Retrieve the contents of a z/OS data set or member” API is “text/plain” type. You can use below syntax to get the content of the data set from the response data and assign the value into a workflow instance variable “dsContent”.

<rest>

    <httpMethod>GET</httpMethod>

    <uriPath substitution="true">/zosmf/restfiles/ds/${instance-dataSetName}</uriPath>

    <expectedStatusCode>200</expectedStatusCode>

    <propertyMapping mapTo="dsContent">[]</propertyMapping>

</rest>