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.
| 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.
| 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. |
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 following resource profile in the ZMFAPLA class: <SAF-prefix>.ZOSMF.WORKFLOW.WORKFLOWS. By default, any user ID with z/OSMF administrator authority can access the z/OSMF workflow services.
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:
| 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:
- HTTP 200 OK
- 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.