REST steps

A typical use for a REST step would be to obtain values for your workflow and assign the values to variables defined in the workflow. Suppose, for example, that your workflow requires an IP address and a port number from a REST endpoint. The REST step can be used to invoke this REST endpoint and map the values from the REST endpoint response body to your IP address and port number variables.

An example of a REST step that obtains an IP address and port number is shown in Figure 1.

How the user interacts with a REST step

From the user’s perspective, when a step definition includes the <rest> element, the Workflows task enables the Perform button on the step instructions page. When the user presses Finish, the perform wizard issues the REST request. The behavior of the wizard is further controlled through the sub-elements that you define within the <rest> element.

Elements of a REST step

In a workflow definition, a REST step is defined with the <rest> element and a number of sub-elements and attributes that provide details about the REST request. The details include the HTTP method, URI path, query parameters, request body, expected status code, and actual status code. The <rest> element also defines any mapping properties that you use to save the JSON properties (name and value pairs) in the response body to workflow variables.

Mapping the returned data to variables

You can assign the values that are returned from a GET request to variables that are defined in your workflow. To do so, include the <propertyMapping> element on the <rest> tag. This element identifies the required values in the JSON response body and saves the values to workflow variables. On the <propertyMapping> element, specify the value to be assigned on the "mapTo" attribute. You can specify multiple <propertyMapping> elements in a REST step.

In the following example, the workflow owner is defined in a property mapping.

<propertyMapping mapTo="workflow_owner">["name"]</propertyMapping>

If the response body is: 

{ "name": "John" }

the workflow variable "workflow_owner" is assigned the value John.

Specifying substitution variables for REST step elements

You can specify substitution variables as values for the elements <hostname>, <port>, <uriPath>, <queryParameters>, and <requestBody>. Doing so allows you to set the values for these elements dynamically from the workflow variables.

<step name="get_ip_and_port_data">
        <title>Get values for workflow variables ip_addr and port from REST API call.</title>
        <description>Invoke RESTful API to get IP address and port number.</description>
	<prereqStep name="get_stack_data_for_rest_request"/>
        <instructions substitution="false">	Execute step to retrieve the IP address and port number 
        from z/OS Communications Server.</instructions>
        <weight>10</weight>
        <skills>REST</skills>
		<rest>
		<httpMethod>POST</httpMethod>
		<uriPath>/zosmf/workflow/WorkflowManager/cloud/ipaddr/</uriPath>
		<requestBody substitution="true">
{
	"name" : "GGAIPA",
	"description" : "IP address created by GGA", 
	"ipaddr" : "1.1.1.2",
	"usageType" : "Internal",
	"workloadDeploymentGroup" : "/wdg/12345",
	"deploymentId" : "deployerA",
	"recoveryMethod" : "MANUAL_DISRUPTIVE", 
	"hostName" : "mvstst1",
	"stack" :  
		{
			"stackId" : "${instance-stack_id}",	
			"stackname" : "${instance-stack_name}"
		},
	"boundTcpPorts"	: [
		"4",
		"81"
	]
}			
		</requestBody>
		<expectedStatusCode>201</expectedStatusCode>
		<actualStatusCode mapTo="status_code" />
		<propertyMapping mapTo="ip_address">["ipaddr"]</propertyMapping>
		<propertyMapping mapTo="port0">["boundPorts"][0]</propertyMapping>
		<propertyMapping mapTo="port1">["boundPorts"][1]</propertyMapping>
		</rest>
	</step>