Retrieve a workflow definition
You can use this operation to retrieve the contents of a z/OSMF workflow definition from a z/OS system.
HTTP method and URI path
GET /zosmf/workflow/rest/<version>/workflowDefinition
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
- definitionFilePath
- Specifies the location of the workflow definition file, which is either a UNIX path name (including the file name) or a fully qualified z/OS data set name. This parameter is required.
- returnData
- Use this optional parameter to request more information about
the workflow definition file. Include one or both of the following
attributes on the returnData parameter:
- steps
- Returns an array of step-definition objects; one object for each step in the workflow. Table 3 lists the fields in the step-definition JSON object.
- variables
- Returns an array of variable-definition objects; one object for each variable that is referenced in the workflow. Table 7 lists the fields in the variable-definition JSON object.
To specify both attributes, separate the attributes by a comma (','), as follows:
Do not enclose the attributes in quotation marks.returnData=steps,variables
Description
This operation retrieves the content of a z/OSMF workflow definition. You can optionally expand the returned information through the specification of query parameters.
A workflow definition might consist of multiple XML files, including a primary file and possibly other files that are included by the primary file. The workflow definition resides in a z/OS UNIX file system or a z/OS data set.
On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 2. If you include the optional query parameter returnData on the request, the operation can return more information about the workflow definition steps or variables, or both. For the format of this information, see the JSON objects that are described in Table 3 and Table 7.
Authorization requirements
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 403 Forbidden | The requestor user ID is not permitted to the workflow definition file. |
HTTP 404 Not found | The specified workflow definition file was not found. This resource is specified on the query parameter definitionFilePath. |
Additional standard status codes can be returned, as described in HTTP status codes.
Response content
Field name | Type | Description |
---|---|---|
workflowDefaultName | String | Identifies the default name for the workflow. This value is shown in the in the workflow name field of the Workflows task when the user creates a new 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. |
vendor | String | Name of the vendor that provided the workflow definition file. |
workflowDefinitionFileMD5Value | String | A 128-bit hash value that z/OSMF generates to uniquely identify the workflow definition file. |
isCallable | String | Indicates the callable scope for the workflow,
as follows:
This property is null when the workflow cannot be called by another workflow. |
scope | String | Indicates the singleton scope for the workflow, as follows:
|
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. |
steps | Array of objects | Array of one or more step-definition objects that contain details about each of the steps in the workflow definition file. This property is returned only when the query parameter returnData specifies the attribute steps. See the Format of the step-definition object section for a list of the fields in the step-definition object. |
variables | Array of objects | Array of one or more variable-definition objects that contain details about the variables that are defined or referenced in the workflow definition file. This property is returned only when the query parameter returnData specifies the attribute variables. Table 7 lists the fields in the variable-definition object. |
Format of the step-definition object
Field name | Type | Description |
---|---|---|
name | String | Name of the step. |
title | String | Step title. |
description | String | Step description. |
prereqStep | Array of strings | 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. |
optional | Boolean | Indicates whether the step is optional (true or false). |
steps | Array of objects | For a parent step, this property is an array of one or more step-definition objects that contain details about each of the steps in the workflow. For a leaf step, this property is null. |
Field name | Type | Description |
---|---|---|
calledWorkflowDescription | String | For a step that calls another workflow for execution, this property contains the description of the called workflow. This information might include details such as the name and location of the workflow definition file that is used to create the called workflow. |
calledWorkflowID | String | For a step that calls another workflow for execution, this property contains the workflow ID for the called workflow. |
calledWorkflowMD5 | String | For a step that calls another workflow for execution, this property contains the 128-bit hash value that can be used to identify the called workflow. |
calledWorkflowDefinitionFile | String | For a step that calls another workflow for execution, this property contains the path name of the workflow definition file for the called workflow. |
calledWorkflowVersion | String | For a step that calls another workflow for execution, this property contains the version of the workflow definition file for the called workflow. |
callingStepAutoEnable | Boolean | For a step that calls another workflow for execution, this property indicates whether the step is to be performed automatically when all prerequisite steps are completed, and no user inputs are required (true or false). |
callingStepWeight | Integer | For a step that calls another workflow for execution, this property indicates the relative difficulty of the step compared to other steps within this workflow (an integer value 1 - 1000). |
callingStepSkills | String | For a step that calls another workflow for execution, this property indicates the type of skills that are required to perform the step. |
Field name | Type | When returned | Description |
---|---|---|---|
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. |
autoEnable | Boolean | All step types | Indicates whether the step is to be performed automatically when all prerequisite steps are completed, and no user inputs are required (true or false). |
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. |
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 | All step types | Detailed instructions on what the user must do to perform the step. |
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 are therefore 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. |
output | String | Template steps only | Indicates the default 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. |
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. |
port | String | REST steps only | Port number that is associated with the REST request. |
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. |
propertyMappings | Array of objects | REST steps only | An array of property mappings, the format of
which is:
In the mappings:
|
queryParameters | String | REST steps only | For a REST request that includes query parameters, this property contains the query parameters. 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. |
saveAsDataset | String | Template steps only | Data set name (fully qualified, no quotation marks) that contains the saved JCL. |
saveAsUnixFile | String | Template steps only | UNIX file name (absolute name) that contains the saved JCL. |
schemeName | String | REST steps only | The scheme name that is used for the REST request. For example: http. |
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 | All step types | The type of skills that are required to perform the step. |
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 for a JCL job, a REXX exec program, or a UNIX shell script. |
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. |
uriPath | String | REST steps only | The URI path to use for the REST request. |
variable-specifications | Array of objects | All step types | An array of variable-specification-info objects, the format of which is described in Table 6. |
weight | Integer | All step types | The relative difficulty of the step compared to other steps within this workflow (an integer value 1 - 1000). |
Format of the variable-specification-info object
Field name | Type | Description |
---|---|---|
name | String | Name of the variable. |
scope | String | Variable scope, which is either instance or global. |
required | Boolean | Indicates whether the variable is required (true or false). |
Format of the variable-definition object
Field name | Type | Description |
---|---|---|
name | String | Name of the variable. |
scope | String | Variable scope, which is either instance or global. |
abstract | String | A brief description of the variable. |
category | String | Name of the logical grouping to which the variable belongs. |
choice | Array of strings | The choice value for the variable. |
decimalPlaces | Integer | Maximum number of decimal places that can be specified. |
default | String | Default value of the variable. |
description | String | Description of the variable. |
exposeToUser | Boolean | Indicates whether the variable is displayed to the user in the Workflows task. |
maxLength | Integer | Maximum length of the variable value. |
maxValue | String | Maximum value of the variable. |
minLength | Integer | Minimum length of the variable value. |
minValue | String | Minimum value of the variable. |
promptAtCreate | Boolean | Indicates whether the user is prompted to specify a value for the variable during the create workflow process. |
regularExpression | String | Provides a standard regular expression that constrains the variable value, as an alternative to the available validation types. |
requiredAtCreate | Boolean | Indicates whether a value must be specified for the variable during the create workflow process. |
type | String | Type of variable. |
validationType | String | Specifies the validation type for the variable. |
visibility | String | Indicates whether the variable is displayed to the Workflows task user (either public or private). |
Example HTTP interaction
In the following example, the GET method is used to retrieve a workflow definition. The location of the workflow definition is specified on the query parameter definitionFilePath. The query parameter returnData=steps,variables is included to request more information about the workflow steps and variables.
GET
/zosmf/workflow/rest/1.0/workflowDefinition
?definitionFilePath=/usr/lpp/zosmf/V2R1/samples/workflow_sample_automation.xml
&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: 5822
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
date: Wed, 24 Aug 2016 18:30:34 GMT
content-type: application/json; charset=UTF-8
{
"workflowDefinitionFileMD5Value": "bd1a9b495dfe37ca7837ab7758433bb0",
"category": "configuration",
"scope": "none",
"isCallable": null,
"workflowID": "programExecutionSample",
"workflowDescription": "Sample that demonstrates how to run an executable program from a step.\n\t",
"vendor": "IBM",
"workflowVersion": "1.0",
"workflowDefaultName": null,
"steps": [
{
"skills": "System Programmer",
"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 ",
"weight": 1,
"maxLrecl": 1024,
"instructions": "This step outputs some variables and prints a few words.\n ",
"variable-specifications": [
{
"scope": "instance",
"name": "st_group",
"required": true
},
{
"scope": "instance",
"name": "st_user",
"required": true
},
{
"scope": "instance",
"name": "procNameVariable",
"required": true
}
],
"outputVariablesPrefix": "prefix:",
"saveAsDataset": null,
"isRestStep": false,
"submitAs": "TSO-UNIX-shell",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"title": "A step that runs a UNIX shell script.",
"failedPattern": [
"failed.*"
],
"autoEnable": "false",
"regionSize": 50000,
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"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",
"name": "TSO-UNIX-shell_Execution",
"optional": false,
"scriptParameters": "para1",
"output": null,
"timeout": 60
},
{ "skills": "System Programmer",
"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 ",
"weight": 1,
"maxLrecl": 1024,
"instructions": "This step outputs some variables and prints a few words.\n ",
"variable-specifications": [
{
"scope": "instance",
"name": "st_group",
"required": true
},
{
"scope": "instance",
"name": "st_user",
"required": true
},
{
"scope": "instance",
"name": "procNameVariable",
"required": true
}
],
"outputVariablesPrefix": "prefix:",
"saveAsDataset": null,
"isRestStep": false,
"submitAs": "TSO-UNIX-REXX",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"title": "A step that runs a UNIX REXX exec program.",
"failedPattern": [
"failed.*"
],
"autoEnable": "false",
"regionSize": 50000,
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"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",
"name": "TSO-UNIX-REXX_Execution",
"optional": false,
"scriptParameters": "para1",
"output": null,
"timeout": 60
},
{
"skills": "System Programmer",
"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 meet a timeout.\"\n ",
"weight": 1,
"maxLrecl": 1024,
"instructions": "This step outputs some variables and prints a few words.\n ",
"variable-specifications": [
{
"scope": "instance",
"name": "st_group",
"required": true
},
{
"scope": "instance",
"name": "st_user",
"required": true
},
{
"scope": "instance",
"name": "procNameVariable",
"required": true
}
],
"outputVariablesPrefix": "prefix:",
"saveAsDataset": null,
"isRestStep": false,
"submitAs": "TSO-REXX",
"saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
"title": "A step that runs a REXX exec program.",
"failedPattern": [
"failed.*" ],
"autoEnable": "false",
"regionSize": 50000,
"successPattern": "success.*",
"procName": "${instance-procNameVariable}",
"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",
"name": "TSO-TSO-REXX_Execution",
"optional": false,
"scriptParameters": "para1",
"output": null,
"timeout": 60
} ],
"productVersion": "Version 1",
"productName": "Product ABC",
"productID": "ABC123",
"variables": [ {
"abstract": "User ID for the started task.",
"scope": "instance",
"regularExpression": "^[0-9A-Z$#@]{1,8}$",
"choice": null,
"visibility": "private",
"type": "string",
"decimalPlaces": null,
"exposeToUser": false,
"category": "Started",
"default": "MYSTUSER",
"promptAtCreate": false,
"description": "The user ID under whose authority the new started task will run.\n\t",
"validationType": "USERID",
"name": "st_user",
"requiredAtCreate": false
},
{
"abstract": "Group name for the started task.",
"scope": "instance",
"regularExpression": "^[A-Z$#@]{1}[0-9A-Z$#@]{0,7}$",
"choice": null,
"visibility": "private",
"type": "string",
"decimalPlaces": null,
"exposeToUser": false,
"category": "Started",
"default": "SYS1",
"promptAtCreate": false,
"description": "The group name under whose authority the started task will run.\n\t",
"validationType": "GROUP",
"name": "st_group",
"requiredAtCreate": false
},
{
"abstract": "Enter a procedure name for running the program.",
"scope": "instance",
"choice": null,
"visibility": "private",
"type": "string",
"decimalPlaces": null,
"exposeToUser": false,
"category": "TSO procName",
"default": null,
"maxLength": 1000000,
"promptAtCreate": false,
"description": "This value is used to specify a procedure name (proc name) for the
TSO/E address space \n\tthat is used to run the program.\n\t",
"name": "procNameVariable",
"requiredAtCreate": false }
]
}