Get the properties of a workflow
You can use this operation to retrieve the properties of a z/OSMF workflow.
HTTP method and URI path
GET /zosmf/workflow/rest/<version>/workflows/<workflowKey>
- <version> identifies the version of the z/OSMF workflow service. The following value is valid: 1.0.
- <workflowKey> identifies the workflow to be queried.
Query parameters
- returnData
- This optional query parameter is used to request information about
the workflow steps and variables. Include one or both of the following
attributes on the returnData parameter:
- steps
- Returns an array of step-info objects; one object for each step in the workflow. Table 4 lists the fields in the step-info JSON object.
- variables
- Returns an array of variable-info objects; one object for each variable that is referenced in the workflow. Table 6 lists the fields in the variable-info JSON object.
returnData=steps,variables
Do
not enclose the attributes in quotation marks.The response data is limited by the access type of the workflow. For information, see Effects of access type on the returned data.
Description
This operation retrieves the properties of a z/OSMF workflow. You can optionally expand the returned information through the specification of query parameters. On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 2.
For the format of this information, see the JSON objects that are described in Table 4 and Table 6.
Authorization requirements
Effects of access type on the returned data
If you include the optional query parameter returnData on the request, the operation can return information about the workflow steps or variables, or both. The amount of data that can be retrieved about the workflow steps or variables can be restricted by the workflow access type. This value is specified by the workflow owner at workflow creation time.
Generally, a workflow with a public access type is less restricted in the amount of data that is available to the requestor. A workflow with a restricted or private access type is more secure, and requires the caller user ID to be a workflow owner, step owner, or step assignee to use or access areas in the workflow.
All requestors can retrieve the workflow common properties. This data includes the information that is shown in Table 2.
For variables data, the workflow owner can retrieve all of the variable properties for the workflow. The step owner and step assignees can retrieve the variable properties that are associated with steps they own. Other users cannot retrieve this data; requests for details about the variables from these users result in empty arrays being returned.
Step data type | Steps properties | Public access workflow | Restricted access workflow | Private access workflow |
---|---|---|---|---|
Step common properties |
|
This data can be retrieved by all requestors. | This data can be retrieved by:
|
This data can be retrieved by:
|
Step restricted properties |
|
This data can be retrieved by all requestors. | This data can be retrieved by:
|
The workflow owner can retrieve this data
for all steps. The step owner and assignees can retrieve this data for their steps only. |
Step detail properties |
|
The workflow owner can retrieve this data
for all steps. The step owner and assignees can retrieve this data for their steps only. |
The workflow owner can retrieve this data
for all steps. The step owner and assignees can retrieve this data for their steps only. |
The workflow owner can retrieve this data
for all steps. The step owner and assignees can retrieve this data for their steps only. |
HTTP status codes
On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 2.
Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code that is indicated and associated error message.
HTTP error status code | Description |
---|---|
HTTP 404 Not found | The specified workflow key was not found; the workflow does not exist. |
Additional standard status codes can be returned, as described in HTTP status codes.
Response content
On successful completion, the response body is a JSON object that contains the retrieved data. Table 2 lists the fields in the JSON 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. |
vendor | String | Name of the vendor that provided the workflow definition file. |
owner | String | User ID of the workflow owner. |
system | String | Full name of the z/OS system on which the workflow is to be performed. This value is in the format sysplex.sysname. |
category | String | Category of the workflow, which is either general or configuration. |
productID | String | Identifier of the product or component that is being configured through the workflow, such as the product identifier (PID) or function modification identifier (FMID). |
productName | String | Name of the product or component that is being configured through the workflow. |
productVersion | String | Version and release of the product or component that is configured through the workflow. |
percentComplete | Integer | Percentage of the workflow that is completed. z/OSMF calculates this value based on the number of steps in the workflow and the relative weighting value of each step. |
statusName | String | Indicates the current workflow status, as
follows:
|
automationStatus | Object | An automation-info object that contains details
about the most recent start automation request for the workflow. The
content of this property depends on the following factors:
Table 3 lists the fields in the automation-info object. |
steps | Array of objects | Array of one or more step-info objects that contain details about each of the steps in the workflow. This property is returned only when the query parameter returnData specifies the attribute steps. The content of this array depends on what the requestor is permitted to see. For more information, see Description. Table 4 lists the fields in the step-info object. |
variables | Array of objects | Array of one or more variable-info objects that contain details about the variables that are used in the workflow. This property is returned only when the query parameter returnData specifies the attribute variables. The content of this array depends on what the requestor is permitted to see. For more information, see Description. Table 6 lists the fields in the variable-info object. |
Format of the automation-info object
Field name | Type | Description |
---|---|---|
startUser | String | User ID of the user who initiated the automation processing. |
startedTime | Timestamp | Time that automation processing started. The timestamp data type is used to mean a non-negative Long integer quantity where the value represents a date and time expressed as the number of milliseconds since midnight on January 1, 1970 UTC. |
stoppedTime | Timestamp | Time that automation processing stopped. If automation is still in progress, this property is set to null. The timestamp data type is used to mean a non-negative Long integer quantity where the value represents a date and time expressed as the number of milliseconds since midnight on January 1, 1970 UTC. |
currentStepName | String | Name of the step that is being processed automatically. Or, the name of the step that caused automation to stop. If automation is stopped and the workflow status is complete, this property is set to null. |
currentStepNumber | String | The step number. If automation is stopped and the workflow status is complete, this property is set to null. |
currentStepTitle | String | Step title. If automation is stopped and the workflow status is complete, this property is set to null. |
messageID | String | Message identifier for the accompanying message. If automation is still in progress, this property is set to null. |
messageText | String | Message text that describes the reason that automation is stopped. If automation is still in progress, this property is set to null. |
Format of the step-info object
- All step types
- Properties that are returned for all step types.
- Calling steps
- Properties that are returned for a step that calls another workflow for execution.
- Template steps
- Properties that are returned for a step that runs a program, such as a batch job, REXX exec, or UNIX shell script.
- REST steps
- Properties that are returned for a step that issues a REST API request, such as a GET or PUT request.
With regard to returned data, a template step and a REST step are mutually exclusive. The returned information for a template step does not include the properties for a REST step. Likewise, the returned information for a REST step does not include the properties for a template step. To help you identify which steps are REST steps, the step-info object includes the isRestStep property, set to true or false.
Field name | Type | When returned | Description |
---|---|---|---|
name | String | All step types | Name of the step. |
actualStatusCode | String | REST steps only | The actual HTTP status code received from the REST API request. To obtain this value, map it to a workflow variable. |
assignees | String | Calling steps and template steps | Step assignees; one or more user IDs that are assigned to the step. Multiple items are separated by commas. |
autoEnable | Boolean | All step types | Indicates whether the step can be performed automatically when all prerequisite steps are completed, and no user inputs are required. |
calledInstanceURI | String | Calling steps only | For a step that calls another workflow for execution, this property contains
the URI path of the called workflow instance. You can use this value to retrieve information about
the called workflow. This property is null until the step is performed and either a new instance of the called workflow is created or an existing instance is found. |
calledWorkflowID | String | Calling steps only | This property contains the workflow ID of a workflow definition file; it is used to help locate an existing workflow instance when this step is performed. This property is null when the property calledWorkflowMD5 is specified. |
calledWorkflowVersion | String | Calling steps only | This property contains the workflow version of a workflow definition file; it
is used to help locate an existing workflow instance when this step is performed. This property:
|
calledWorkflowMD5 | String | Calling steps only | This property contains the 128-bit hash value of a workflow definition file; it is used to help locate an existing workflow instance when this step is performed. This property is null when the property calledWorkflowID is specified. |
calledWorkflowDescription | String | Calling steps only | This property contains a description of the workflow to be called, from the point of view of the calling workflow. |
calledWorkflowDefinitionFile | String | Calling steps only | This property contains the name of the workflow definition file that will be used to create a new workflow if an existing instance is not found when this step is performed. This property might be null. |
description | String | All step types | Step description. |
expectedStatusCode | String | REST steps only | The expected HTTP status code from the REST API request. If the expectedStatusCode value does not match the actualStatusCode value, the workflow step fails. This behavior is similar to what happens when a template step returns a return code that is greater than the allowed maximum return code. |
failedPattern | Array of strings | Template steps only | Optional regular expression that can be returned for program execution failures. This property might be null. |
hasCalledWorkflow | Boolean | Calling steps and template steps | Indicates whether this step calls another workflow (true or false). If true,
this step is a "calling" step, that is, it calls another workflow for execution. If false, it is a
template step. This property is returned only when steps=null, which indicates a leaf step. |
hostname | String | REST steps only | Indicates the hostname or IP address of the site to which the REST request is directed. For example: www.ibm.com. |
httpMethod | String | REST steps only | Indicates the HTTP method that is used for issuing the REST API request. The
possible values are:
|
instructions | String | Template steps only | Detailed instructions on what the user must do to perform the step. |
instructionsSub | Boolean | Template steps only | Indicates whether the step instructions contain variables (true or false). |
isConditionStep | Boolean | Calling steps and template steps | Indicates whether this step is a conditional step (true or false). |
isRestStep | Boolean | All step types | Indicates whether this step is a REST API step (true or false). When set to
true, the following properties contain details about the REST request. Otherwise, these properties
are set to null.
The following step properties are not applicable for a REST step and thus, are omitted
from the output:
|
maxLrecl | Integer | Template steps only | For a step that submits a job, this value specifies the maximum record length, in bytes, for the input data for the job. This value is an integer 80 - 1024. The default is 1024. |
optional | Boolean | All step types | Indicates whether the step is optional (true or false). |
output | String | Template steps only | Indicates the name of the output file produced by the step (a data set or UNIX file). The output file can contain variables and values that are used by subsequent steps. |
outputSub | Boolean | Template steps only | Indicates whether the output file name contains variable substitution (true or false). |
outputVariablesPrefix | String | Template steps only | For a step that creates a variable, this property contains a prefix that identifies a string as a variable. This property might be null. |
owner | String | Calling steps and template steps | User ID of the step owner. |
port | String | REST steps only | Port number that is associated with the REST request. |
portSub | Boolean | REST steps only | Indicates whether the port number contains variable substitution (true or false). |
prereqStep | Array of strings | All step types | Lists the names of the steps that must be completed before this step can be performed. Up to 499 prerequisite steps can be defined for a step. |
procName | String | Template steps only | For a step that runs a program under TSO/E, this property contains the name of the logon procedure that is used to log into the TSO/E address space. If no value was specified for the step, the default is IZUFPROC. |
queryParameters | String | REST steps only | For a REST request that includes query parameters, this property contains the query parameters. Otherwise, this property is null. |
queryParametersSub | Boolean | REST steps only | This property indicates whether the query parameters contain variable substitution (true or false). Otherwise, this property is null. |
regionSize | String | Template steps only | For a step that runs a program under TSO/E, this property contains the region size for the TSO/E address space. If no value was specified for the step, the default is 50000. |
requestBody | String | REST steps only | For a REST request that includes a request body, this property contains the request body. Otherwise, this property is null. |
requestBodySub | Boolean | REST steps only | This property indicates whether the request body variable substitution (true or false). Otherwise, this property is null. |
returnCode | String | Template steps only | For a step that submits a job to run, this property indicates the return code that was returned when the job was submitted. |
saveAsDataset | String | Template steps only | Data set name (fully qualified, no quotation marks) that contains the saved JCL. |
saveAsDatasetSub | Boolean | Template steps only | Indicates whether the data set name contains variable substitution (true or false). |
saveAsUnixFile | String | Template steps only | UNIX file name (absolute name) that contains the saved JCL. |
saveAsUnixFileSub | Boolean | Template steps only | Indicates whether the UNIX file name contains variable substitution (true or false). |
schemeName | String | REST steps only | The scheme name that is used for the REST request. For example: http. |
schemeNameSub | Boolean | REST steps only | Indicates whether the scheme name contains variable substitution (true or false). |
scriptParameters | Array of strings | Template steps only | For a step that runs a program, this property contains the input parameters that can be set by the step owner. This property might be null. |
skills | String | Calling steps and template steps | The type of skills that are required to perform the step. |
state | String | All step types | State of the step. One of the following status indicators is displayed:
|
stepNumber | String | All step types | The step number. Steps are numbered to indicate the sequence in which steps are to be performed. For example, the first step in a workflow is 1. |
steps | Array of objects | All step types | For a parent step, this is a nested array of step-info objects. For a leaf step, this property is null. Check this property first before you check the other, non-common step properties. A non-null value here means that the calling step properties are omitted, as are the template step properties and the REST step properties. |
submitAs | String | Template steps only | Indicates the type of executable program: JCL job, a REXX exec, or a UNIX shell script, which
includes a REXX exec that is written for the UNIX shell environment. The possible values are the
following:
|
successPattern | String | Template steps only | Regular expression that is returned for a successful program execution. |
template | String | Template steps only | Indicates the template that is used to run a program or batch job (inline or external file). |
templateSub | Boolean | Template steps only | Indicates whether template contains variable substitution (true or false). The default is false. |
timeout | String | Template steps only | For a step that runs a REXX exec or UNIX shell script, this property contains the maximum amount of time that the program can run before it is ended by a timeout condition. |
title | String | All step types | Step title. |
uriPath | String | REST steps only | The URI path to use for the REST request. |
uriPathSub | Boolean | REST steps only | Indicates whether the URI path contains variable substitution (true or false). |
userDefined | Boolean | All step types | Indicates whether the step was added manually to the workflow (true or false). If true, the step was added by the workflow owner, using the Update Workflow Steps action in the Workflows table. If false, the step was defined in the workflow definition that was used to create the workflow. |
variable-references | Array of objects | Template steps only | An array of variable-reference objects, the format of which is described in Table 5. |
weight | Integer | Calling steps and template steps | The relative difficulty of the step compared to other steps within this workflow (an integer value 1 - 1000). |
Format of the variable-reference object
Field name | Type | Description |
---|---|---|
name | String | Name of the variable. |
scope | String | Variable scope, which is either instance or global. |
Format of the variable-info object
Field name | Type | Description |
---|---|---|
name | String | Name of the variable. |
scope | String | Variable scope, which is either instance or global. |
type | String | Type of variable, which is one of the following
values:
|
value | String | Variable value. |
visibility | String | Public or private. |
Example HTTP interaction
In the following example, the GET method is used to retrieve information about a workflow. The workflow is uniquely identified by the workflow key, which is represented by the following string value: 26f1fd84-058b-443c-8e06-5ec318ecdb86. The query parameter returnData=steps,variables is included to request more information about the workflow steps and variables.
GET /zosmf/workflow/rest/1.0/workflows/26f1fd84-058b-443c-8e06-5ec318ecdb86?returnData=steps,variables
HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Authorization: Basic em9zbWZhZDp6b3NtZmFk
An example of the response is shown in the figures that follow.
HTTP/1.1 200 OK
content-length: 9155
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
date: Wed, 24 Aug 2016 18:30:33 GMT
content-type: application/json; charset=UTF-8
{
"percentComplete": 0,
"workflowDefinitionFileMD5Value": "bd1a9b495dfe37ca7837ab7758433bb0",
"statusName": "in-progress",
"vendor": "IBM",
"accountInfo": null,
"workflowVersion": "1.0",
"automationStatus": null,
"steps": [
{
"skills": "System Programmer",
"hasCalledWorkflow": false,
"weight": "1",
"instructions": "This step outputs some variables and prints a few words.\n ",
"assignees": "zosmft1",
"state": "Ready",
"saveAsDataset": null,
"stepNumber": "1",
"templateSub": true,
"submitAs": "TSO-UNIX-shell",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"userDefined": false,
"title": "A step that runs a UNIX shell script.",
"autoEnable": false,
"variable-references": [
{
"scope": "instance",
"name": "st_group"
},
{
"scope": "instance",
"name": "st_user"
},
{
"scope": "instance",
"name": "procNameVariable"
}
],
"regionSize": 50000,
"instructionsSub": false,
"description": "In this step, you submit an inline UNIX shell script for immediate
processing \n\t\ton the host system. In this example, the step is
expected to complete successfully.\n\t\t",
"optional": false,
"name": "TSO-UNIX-shell_Execution",
"outputSub": false,
"scriptParameters": "para1",
"template": "\n#!/bin/sh\necho \"this is a sample to submit shell script to run
immediately\"\necho \"the first parameter is
:\" $1 \t\necho ${instance-st_user}\necho prefix:st_group = SYS123\
necho prefix:st_user = USERS\necho \"This symbol is used to
indicate success\"\t\necho \"The program ran successfully !!\"\t\t\n ",
"returnCode": null,
"saveAsDatasetSub": false,
"maxLrecl": 1024,
"outputVariablesPrefix": "prefix:",
"prereqStep": null,
"steps": null,
"isConditionStep": false,
"isRestStep": false,
"saveAsUnixFileSub": true,
"failedPattern": [
"failed.*"
],
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"owner": "zosmft1",
"output": null,
"timeout": 60
},
{
"skills": "System Programmer",
"hasCalledWorkflow": false,
"weight": "1",
"instructions": "This step outputs some variables and prints a few words.\n ",
"assignees": "zosmft1",
"state": "Ready",
"saveAsDataset": null,
"stepNumber": "2",
"templateSub": true,
"submitAs": "TSO-UNIX-REXX",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"userDefined": false,
"title": "A step that runs a UNIX REXX exec program.",
"autoEnable": false,
"variable-references": [
{
"scope": "instance",
"name": "st_group"
},
{
"scope": "instance",
"name": "st_user"
},
{
"scope": "instance",
"name": "procNameVariable"
}
],
"regionSize": 50000,
"instructionsSub": false,
"description": "In this step, you submit an inline UNIX REXX exec for immediate
processing \n\t\ton the host system. In this example, the step is
expected to fail.\n\t\t",
"optional": false,
"name": "TSO-UNIX-REXX_Execution",
"outputSub": false,
"scriptParameters": "para1",
"template": "/* rexx */\nparse arg arg1\nSAY \"this is a sample to submit UNIX REXX
script to run immediately\"\nSAY \"the first parameter is
:\" arg1\nSAY ${instance-st_user}\nSAY \"prefix:st_group =\" SYS123\nSAY \
"prefix:st_user =\" USERS\nSAY \"This symbol is used to indicate failed\"\n ",
"returnCode": null,
"saveAsDatasetSub": false,
"maxLrecl": 1024,
"outputVariablesPrefix": "prefix:",
"prereqStep": null,
"steps": null,
"isConditionStep": false,
"isRestStep": false,
"saveAsUnixFileSub": true,
"failedPattern": [
"failed.*"
],
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"owner": "zosmft1",
"output": null,
"timeout": 60
},
{
"skills": "System Programmer",
"hasCalledWorkflow": false,
"weight": "1",
"instructions": "This step outputs some variables and prints a few words.\n ",
"assignees": "zosmft1",
"state": "Ready",
"saveAsDataset": null,
"stepNumber": "3",
"templateSub": true,
"submitAs": "TSO-REXX",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"userDefined": false,
"title": "A step that runs a REXX exec program.",
"autoEnable": false,
"variable-references": [
{
"scope": "instance",
"name": "st_group"
},
{
"scope": "instance",
"name": "st_user"
},
{
"scope": "instance",
"name": "procNameVariable"
}
],
"regionSize": 50000,
"instructionsSub": false,
"description": "In this step, you submit an inline REXX exec for immediate
processing \n\t\ton the host system. In this example, the processing
is ended by a time-out condition.\n\t\t",
"optional": false,
"name": "TSO-TSO-REXX_Execution",
"outputSub": false,
"scriptParameters": "para1",
"template": "/* rexx */\nparse arg arg1\nSAY \"this is a sample to submit TSO REXX
script to run immediately\"\nSAY \"the first
parameter is :\" arg1\nSAY ${instance-st_user}\nSAY \"prefix:st_group =\"
SYS123\nSAY \"prefix:st_user =\" USERS\nSAY \"This execution will meets timeout.\"\n ",
"returnCode": null,
"saveAsDatasetSub": false,
"maxLrecl": 1024,
"outputVariablesPrefix": "prefix:",
"prereqStep": null,
"steps": null,
"isConditionStep": false,
"isRestStep": false,
"saveAsUnixFileSub": true,
"failedPattern": [
"failed.*"
],
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"owner": "zosmft1",
"output": null,
"timeout": 60
}
],
"access": "Public",
"productVersion": "Version 1",
"productID": "ABC123",
"variables": [
{
"scope": "instance",
"visibility": "private",
"name": "st_user",
"value": null,
"type": "string"
},
{
"scope": "instance",
"visibility": "private",
"name": "st_group",
"value": null,
"type": "string"
},
{
"scope": "instance",
"visibility": "private",
"name": "procNameVariable",
"value": null,
"type": "string"
}
],
"category": "configuration",
"system": "PLEX1.SY1 (SY1_003)",
"workflowName": "workflow_sample_program_execution",
"workflowDescription": "Sample that demonstrates how to run an executable
program from a step.\n\t",
"workflowID": "programExecutionSample",
"owner": "zosmft1",
"jobStatement": null,
"workflowKey": "26f1fd84-058b-443c-8e06-5ec318ecdb86",
"productName": "Product ABC"
}