z/OSMF workflow services

The z/OSMF workflow services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to create and manage z/OSMF workflows on a z/OS system.

Table 1 lists the operations that the z/OSMF workflow services provide.
Table 1. z/OSMF workflow services: operations summary
Operation name HTTP method and URI path
Create a workflow POST /zosmf/workflow/rest/<version>/workflows
Get the properties of a workflow GET /zosmf/workflow/rest/<version>/workflows/<workflowKey>
List the workflows for a system or sysplex GET /zosmf/workflow/rest/<version>/workflows
Start a workflow PUT /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/start
Cancel a workflow PUT /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/cancel
Delete a workflow DELETE /zosmf/workflow/rest/<version>/workflows/<workflowKey>
Retrieve a workflow definition GET /zosmf/workflow/rest/<version>/workflowDefinition
Archive a workflow instance POST /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/archive
List the archived workflows for a system GET /zosmf/workflow/rest/<version>/archivedworkflows
Get the properties of an archived workflow GET /zosmf/workflow/rest/<version>/archivedworkflows/<workflowKey>
Delete an archived workflow DELETE /zosmf/workflow/rest/<version>/archivedworkflows/<workflowKey>
Table 2 describes the variables that can be specified in the z/OSMF workflow services URI paths.
Table 2. z/OSMF workflow services: URI path variables
URI path variable Description
<version> The version of the z/OSMF workflow services API. The following value is valid: 1.0.
<workflowKey> The identifier of a unique instance of a workflow, as returned in the response of the operation that created the workflow.

Using the Swagger interface

You can use the Swagger interface to display information about the z/OSMF workflow REST APIs. For more information, see Using the Swagger interface.

Authorization requirements

Use of the z/OSMF workflow services API requires the client to be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

In addition, the user's z/OS user ID must have:
  • READ access to the <SAF-PREFIX>.ZOSMF.WORKFLOW.WORKFLOWS profile in the ZMFAPLA class.
  • READ access to the <SAF_PREFIX>.*.izuUsers profile in the EJBROLE class. Or, at a minimum, READ access to the <SAF_PREFIX>.IzuManagementFacilityWorkflow.izuUsers resource name in the EJBROLE class.

Error response content

For most 4nn and 5nn HTTP error status codes, additional diagnostic information beyond the HTTP status code is provided in the response body for the request. This information is provided in the form of a JSON object containing the following fields:
Table 3. Error response body elements for the z/OSMF workflow services API
Field name Type Description
messageID String The message identifier identifying the reason for the error.
messageText String The message text that describes the error.

Error logging

Errors from the z/OSMF workflow services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM® Support, if required. For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.

HTTP status codes

The following HTTP status codes are valid:
The request succeeded. A response body is provided, which contains the results of the request.
HTTP 201 Created
The request succeeded and resulted in the creation of an object.
HTTP 202 Accepted
The request was successfully validated and is performed asynchronously.
HTTP 204 No content
The request succeeded, but no content is available to be returned.
HTTP 400 Bad request
The request contained incorrect parameters.
HTTP 401 Unauthorized
The request cannot be processed because the client is not authorized. This status is returned if the request contained an incorrect user ID or password, or both. Or, the client did not authenticate to z/OSMF by using a valid WWW-Authenticate header.
HTTP 403 Forbidden
The server received the request, but rejected it.
HTTP 404 Not found
The requested resource does not exist.
HTTP 405 Method not allowed
The requested resource is a valid resource, but an incorrect method was used to submit the request. For example, the request used the POST method when the GET method was expected.
HTTP 408 Request timed out
The client did not produce a request within the allowed time. The request can be submitted again later.
HTTP 409 Request conflict
The request cannot be processed because of conflict in the request, such as an edit conflict between multiple updates.
HTTP 500 Server error
The server encountered an error when it processed the request. For a more specific indication of the error, check the response for a reason code.
HTTP 501 Not implemented
The request specifies an HTTP method that is not recognized by the server.
HTTP 503 Service unavailable
The request cannot be carried out by the server because of a temporary condition. A suggested wait time might be indicated in a Retry-After header, if one is provided in the response. Otherwise, the requestor can treat the response as a 500 response.
HTTP 504 Gateway timeout
The server, which is acting as a gateway or proxy, did not receive a timely response from the server that was specified in the URI path (for example, HTTP, FTP, LDAP) or an auxiliary server (such as DNS). This access is needed to complete the request. For example, the server was not able to start a remote REXX or UNIX shell interface.