REST steps

A step that issues a Representational State Transfer (REST) request, such as a GET or PUT request, is referred to as a REST step.

For a REST step, the Step Type tab includes the following information about the step:
HTTP Method
Indicates the HTTP method that is used for issuing the REST request. The following values are valid:
  • GET
  • PUT
  • POST
  • DELETE.
Scheme Name
Specifies the hypertext transfer protocol (HTTP) header for the request: HTTP or HTTPS.

To connect to a system other than the local system, specify a scheme name, the host name for the receiving system, and, optionally, a port number for the receiving system. Additionally, for a secured connection (HTTPS), you must also specify the user name and password to be used for logging in to the receiving system.

Scheme name and host name, and the optional port number, are used together. You must specify both scheme name and host name, or neither of them. Otherwise, the workflow fails validation when the user attempts to import the workflow definition into the Workflows task.

If you omit the scheme name, no host name is required. In this case, the REST request is sent to the local z/OSMF server.

Host Name
Host name or IP address of the system to which the REST request is directed. For example: www.ibm.com.

If you specify a scheme name (HTTP or HTTPS), you must also specify a host name. You can optionally specify a port number for the host name.

To omit the host name, leave this field blank. The default is the host name that was defined for the local z/OSMF server, which is "*" by default.

The option Check to use substitution indicates whether variable substitution is used in this field.

Port Number
Port number for the REST request. This value is optional. If you omit it, the default is the port number that was defined for z/OSMF, which is "80" for HTTP requests and "443" for HTTPS requests.

The option Check to use substitution indicates whether variable substitution is used in this field.

User name
z/OS user ID that allows the user to access the specified URI. This value is a user ID that is specified in your installation's z/OS security management facility (for example, RACF).
  • For an HTTPS request, the user name and password are required. These values are used to create a secure request to the specified URI.
  • For an HTTP request, the user name and password are optional. These values are used for basic authentication only.

The option Check to use substitution indicates whether variable substitution is used in this field.

Password
Password or pass phrase that is associated with the user name. For an HTTPS request, the user name and password are required.

In the Workflows task, the password must be a Base64 encoding value.

The option Check to use substitution indicates whether variable substitution is used in this field.
  • When the option Check to use substitution is not selected:

    The Workflow Editor streamlines the process of user input for passwords, enabling users to directly input passwords without the need for entering the Base64 encoding value. The Workflow Editor will store the Base64 encoding password in the definition file. For example, when the string password is entered in the Password field, the Workflow Editor will ultimately store cGFzc3dvcmQ= in the definition file.

  • When the option Check to use substitution is selected:

    Variable substitution is used in this field. Workflow Editor will not obscure the password, and the input entered in the Password field is stored in the definition file.

    For example, you can enter ${instance-PW} in this field, where PW represents an instance variable and should have a Base64 encoding value. The ${instance-PW} is then stored in the definition file.

URI Path
URI path for the REST request. This value is required.

The option Check to use substitution indicates whether variable substitution is used in this field.

Query Parameters
For a GET or POST request, this field contains the query parameters. This value is optional; no default is provided.

The option Check to use substitution indicates whether variable substitution is used in this field.

Request Header
Request header for the REST request. This value is optional; no default is provided.
Specify the contents of the request header as a JSON object, as follows:
  • Use braces '{ }' to enclose the JSON content.
  • Specify each header property as a name-value pair, with the property and its value delineated with a colon (:).
  • For multiple header properties, use commas to separate the properties.
For example: 
{
"X-CSRF-ZOSMF-HEADER": "",
"Content-Type" : "application",
"Accept" : "*/*"
}

The option Check to use substitution indicates whether variable substitution is used in this field.

Request Body
For a PUT or POST request, this field contains the request body. This value is optional; no default is provided.

The option Check to use substitution indicates whether variable substitution is used in this field.

Poll Attributes
You can optionally use polling to find out the status of an asynchronous request. In this field, specify the attributes for polling as follows:
Poll Count Maximum
Specify the number of times to poll before the REST call receives the expected condition. The valid range is 1 - 1000.

The option Check to use substitution indicates whether variable substitution is used in this field.

Wait Time
Specify the time (in seconds) to wait between each poll, up to a maximum of 3600 seconds (1 hour). If you specify this value, you must also specify the poll count maximum.

The option Check to use substitution indicates whether variable substitution is used in this field.

Exit Response Property
Specify the name of the response property, which is the condition to end the polling. A program can check the value of this property to determine whether to exit polling. This property is required if you specify a poll count maximum.
Property Value
Specify the value that indicates that polling should end. For example: "Complete" or 0000.

If the returned value for the property matches this value, the poll exits and returns to the caller. Otherwise, polling continues for the specified poll count maximum. If no match is found in the returned response body within the specified polling limits, the REST step fails.

The exit response property and its value do not support substitution variables. These properties must be set in the workflow definition file.

Certificates
Certificates for the REST request. This value is optional; no default is provided.
Specify the certificate locations as a JSON array, as follows:
  • Use square brackets '[ ]' to enclose the array.
  • For each certificate, provide a fully qualified (absolute) path.
  • For multiple certificates, use commas to separate the locations.
For example:

[
"/tmp/SampleCertificate.cer",
"/tmp/AnotherCertificate.cer"
]

The option Check to use substitution indicates whether variable substitution is used in this field.

Expected Status Code
The expected HTTP status code from the REST request. If this value does not match the actualStatusCode value, the workflow step fails. This value is required.
Actual Status Code Mapping
The actual HTTP status code that is received from the REST request. This value is optional; no default is provided.
Property Mappings
Indicates how properties in the response body are to be mapped to variables in the workflow. This value is optional; no default is provided.
The REST step is enhanced to return the entire response body. If empty square brackets are used for the propertyMapping, the REST step will return the entire response body and map it to the workflow variable specified by the mapTo value. For example: 
<propertyMapping mapTo="responseBody">[]</propertyMapping>
In order to map the entire response body, the response type may need to be updated. For example, if the response is in plain text, the Accept header will need to be updated to "Accept": "text/plain". This update can be done using the requestHeader field in the REST step. For example, assuming you want to map a text response to workflow variable results:
<rest>
:
:
  <propertyMapping mapTo=“results”>[]</propertyMapping>
:
  <requestHeaders>
{
  “Accept” : “text/plain”
}
  </requestHeaders>
</rest>

In the Property Mappings table, you can launch actions to modify or remove the selected mappings, or add mappings.