List the workflows for a system or sysplex

You can use this operation to list the z/OSMF workflows for a system or sysplex.

HTTP method and URI path

GET /zosmf/workflow/rest/<version>/workflows

In this request, the URI path variable <version> identifies the version of the z/OSMF workflow service. The following value is valid: 1.0.

Query parameters

Optionally, your request can include one or more of the following query parameters to filter the results:

workflowName

Workflow name. You can specify a regular expression here to match desired workflow names.

category

Category of the workflow, which is either general or configuration.

system

Nickname of the system on which the workflow is to be performed.

statusName

Workflow status, which can be one of the following values:

in-progress
complete
automation-in-progress
canceled

owner

Workflow owner (a valid z/OS user ID).

vendor

Name of the vendor that provided the workflow definition file.

Observe the following conventions:

Query parameters are optional; you can specify one or more query parameters, as needed.
You use a question mark ('?') to separate the first query parameter from the resource.
To specify multiple query parameters in combination, use an ampersand (&).

Description

This operation retrieves a list of workflows that match your search criteria. You can filter the returned list of workflows through the specification of query parameters. You can, for example, limit the results to workflows by name, or the workflows for a particular z/OS system.

On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 1.

Authorization requirements

See Authorization requirements.

Start of change For the requestor of this service, the response data is limited by the workflow access type. This value is selected by the workflow owner at workflow creation time. All workflows with a public access type are included in the response. To list restricted or private access type workflows, however, the requestor user ID must be a workflow owner, step owner, or step assignee. End of change

Start of change For more information, see Workflow access type. End of change

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned.

Otherwise, a non-successful HTTP status code is returned and the response body is a standard error response body with the message ID and the associated error message. For the codes that can be returned, see HTTP status codes.

Response content

On successful completion, the response body contains one property, called workflows. This property is an array of workflow-info objects. Table 1 lists the fields in the workflow-info object. If no workflows match the filter criteria, HTTP status code 200 (OK) is returned with an empty array.

Table 1. List workflows request: Format of the workflow-info object
Field name	Type	Description
`workflowName`	String	Descriptive name for the workflow.
`workflowKey`	String	Workflow key. A string value, generated by z/OSMF to uniquely identify the workflow instance.
`workflowDescription`	String	Description of the workflow.
`workflowID`	String	Workflow ID. A short, arbitrary value that identifies the workflow.
`workflowVersion`	String	Version of the workflow definition file.
`workflowDefinitionFileMD5Value`	String	The 128-bit hash value that is associated with the workflow definition file that was used to create the workflow.
`instanceURI`	String	Workflow instance URI path, which you can use to retrieve information about the workflow.
`owner`	String	User ID of the workflow owner.
`vendor`	String	Name of the vendor that provided the workflow definition file.

Example HTTP interaction

In the following example, the GET method is used to list the workflows on a system. Here, the query parameter workflowName is included to limit the results to workflows with names that begin with AutomationExample.

Figure 1. Sample request to list workflows

GET /zosmf/workflow/rest/1.0/workflows?workflowName=AutomationExample.* HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Authorization: Basic em9zbWZhZDp6b3NtZmFk

For a successful request, the HTTP response includes a JSON document that contains the requested information. In the following example, one workflow was found to match the request query parameter.

Figure 2. Sample response from a list workflows request

HTTP/1.1 200 OK
content-length: 464
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
date: Wed, 11 Feb 2015 18:30:34 GMT
content-type: application/json; charset=UTF-8

{
    "workflows": [
        {
            "instanceURI": "/zosmf/workflow/rest/1.0/workflows/d043b5f1-adab-48e7-b7c3-d41cd95fa4b0", 
            "owner": "zosmfad", 
            "vendor": "IBM", 
            "workflowDefinitionFileMD5Value": "a8825b7497793bc620b0edffa8b97cd9", 
            "workflowDescription": "Sample demonstrating the use of automated steps in workflow.", 
            "workflowID": "automationSample", 
            "workflowKey": "d043b5f1-adab-48e7-b7c3-d41cd95fa4b0", 
            "workflowName": "AutomationExample|Canceled|1423679433714", 
            "workflowVersion": "1.0"
        }
    ]
}