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.
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> |
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.
- 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
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 z/OSMF log files in IBM z/OS Management Facility Configuration Guide.
HTTP status codes
- 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.