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

You can specify the following query parameters on this request:

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.

workflowDefinitionFileSystem

Nickname of the system on which the specified workflow definition file and any related files reside. The Workflows task obtains the workflow files from this system.

Use the nickname that is specified for the system definition in the z/OSMF Systems task. The nickname is a unique name for the system to differentiate it from existing systems that have the same system and sysplex name. The nickname is 1 - 40 characters long; the valid characters are alphanumeric characters (A-Z, a-z, and 0-9), hyphens (-), and special characters ($ _ # @). Nicknames are case-sensitive; for example, SYSTEM1 and System1 are unique values.

The system can be running in the local sysplex or in another sysplex in your enterprise. If you select a system in a remote sysplex, verify that the system is enabled for single sign-on (SSO). Otherwise, your request must include a valid user ID and password (in the request body) for basic authentication with the remote system.

If you omit this parameter, the Workflows task checks the z/OSMF system of the local sysplex for the workflow definition file and related files, by default.

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, with 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:

returnData=steps,variables

Do not enclose the attributes in quotation marks.

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

See 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 that provides the indicated reason code and associated error message.

Table 1. HTTP error response codes for a retrieve a workflow definition request
HTTP error status code	Description
`HTTP 403 Forbidden`	The requester 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

On successful completion, the response body is a JSON object that contains the retrieved data. Table 2 lists the fields in the object.

Table 2. JSON object that is returned to a retrieve a workflow definition request
Field name	Type	Description
`workflowDefaultName`	String	Identifies the default name for the workflow. This value is shown 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: system An instance of this workflow can be called only from a workflow in the same system. sysplex An instance of this workflow can be called from a workflow anywhere in the sysplex. This property is null when the workflow cannot be called by another workflow.
`containsParallelSteps`	Boolean	For a workflow with automated steps, this property indicates whether the automated steps can be run in parallel (concurrently), thus possibly completing more quickly. For a parallel-steps workflow, this property is `true`. Otherwise, if this property is `false`, automated steps are run one by one in the sequence in which they appear in the workflow, starting from the top of the workflow definition.
`scope`	String	Indicates the singleton scope for the workflow, as follows: system A maximum of one instance of this workflow can exist on any one system in the sysplex. sysplex A maximum of one instance of this workflow can exist in the sysplex. none An existing instance cannot be used. A new instance of this workflow is always created.
`jobsOutputDirectory`	String	Name of the UNIX directory that is used for automatically saving job spool files from the workflow.
`category`	String	Category of the workflow, which is general, configuration, or provisioning.
`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.
`globalVariableGroup`	String	Global variable group for the workflow.
`isInstanceVariableWithoutPrefix`	Boolean	Indicates whether the simplified format is used for references to instance variables. If `true`, variable references are simplified; they omit the prefix `instance-`. If `false`, variable references must include the prefix `instance-`.
`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

The following tables list the fields in the step-definition object:

Table 3
Table 4
Table 5

Table 3. Retrieve a workflow definition request: Fields included in every 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.

Table 4. Retrieve a workflow definition request: Additional fields included in the step-definition object only for a calling step (a step that calls another workflow)
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.

Table 5. Retrieve a workflow definition request: Additional fields included in the step-definition object only for a normal (non-calling) step
Field name	Type	When returned	Description
`actualStatusCode`	String	REST steps only	The actual HTTP status code that is received from the REST API request. To obtain this value, map it to a workflow variable.
`approvers`	Array of objects	All step types	An array of objects that contain: `approver` One or more user IDs that are separated by spaces and can provide approval. `approverSub` This can be set to true or false regardless of whether the approver field uses substitution.
`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: GET PUT POST DELETE
`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. `actualStatusCode` `expectedStatusCode` `hostname` `httpMethod` `port` `propertyMappings` `queryParameters` `requestBody` `schemeName` `uriPath` The following step properties are not applicable for a REST step, and are therefore omitted from the output: `template` `output` `saveAsDataset` `saveAsUnixFile` `submitAs` `maxLrecl`
`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 that is 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 in to 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: `{ "mapFrom": "property", "mapTo": "variable" },` In the mappings: mapFrom Is the property from the REST request. The value of this property is assigned to the specified "mapTo" workflow variable. mapTo Is the workflow variable that is assigned the value from "mapFrom" property.
`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 following values are valid: `"JCL"` `"TSO-REXX"` `"shell-JCL"` `"TSO-REXX-JCL"` `"TSO-UNIX-REXX"` `"TSO-UNIX-shell"`
`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 times out.
`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

Table 6 lists the fields in the variable-specification-info object.

Table 6. Retrieve a workflow definition request: 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

Table 7 lists the fields in the variable-definition object.

Table 7. Retrieve a workflow definition request: 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.
`valueMustBeChoice`	Boolean	Indicates whether the variable value must come from the provided choices. If `true`, the user must choose from the predefined values. If `false`, the user can enter a custom value.
`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.

Figure 1. Sample request to get a workflow definition

GET 
/zosmf/workflow/rest/1.0/workflowDefinition
?definitionFilePath=/usr/lpp/zosmf/samples/workflow_sample_program_execution.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.

Figure 2. Sample response from a get workflow definition request (Part 1 of 3)


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: Thur, 12 Mar 2020 18:30:34 GMT
content-type: application/json; charset=UTF-8
{
    "workflowDefaultName": null,
    "isInstanceVariableWithoutPrefix": false,
    "variables": [
        {
            "visibility": "private",
            "exposeToUser": false,
            "promptAtCreate": false,
            "description": "This value is used to specify a procedure name (proc name) for the TSO/E address space \n\t
                            that is used to run the program.\n\t",
            "abstract": "Enter a procedure name for running the program.",
            "type": "string",
            "requiredAtCreate": false,
            "default": null,
            "decimalPlaces": null,
            "valueMustBeChoice": false,
            "scope": "instance",
            "name": "procNameVariable",
            "category": "TSO procName",
            "choice": null
        },
        {
            "visibility": "private",
            "exposeToUser": false,
            "regularExpression": "^[A-Z$#@]{1}[0-9A-Z$#@]{0,7}$",
            "promptAtCreate": false,
            "validationType": "GROUP",
            "description": "The group name under whose authority the started task will run.\n\t",
            "abstract": "Group name for the started task.",
            "type": "string",
            "requiredAtCreate": false,
            "default": "SYS1",
            "decimalPlaces": null,
            "valueMustBeChoice": false,
            "scope": "instance",
            "name": "st_group",
            "category": "Started",
            "choice": null
        },
        {
            "visibility": "private",
            "exposeToUser": false,
            "regularExpression": "^[0-9A-Z$#@]{1,8}$",
            "promptAtCreate": false,
            "validationType": "USERID",
            "description": "The user ID under whose authority the new started task will run.\n\t",
            "abstract": "User ID for the started task.",
            "type": "string",
            "requiredAtCreate": false,
            "default": "MYSTUSER",
            "decimalPlaces": null,
            "valueMustBeChoice": false,
            "scope": "instance",
            "name": "st_user",
            "category": "Started",
            "choice": null
        }
    ],

Figure 3. Sample response from a get workflow definition request (Part 2 of 3)


    "productID": "ABC123",
    "workflowDescription": "Sample that demonstrates how to run an executable program from a step.\n\t",
    "steps": [
        {
            "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            ",
            "instructions": "This step outputs some variables and prints a few words.\n        ",
            "autoEnable": "false",
            "maxLrecl": 1024,
            "submitAs": "TSO-UNIX-shell",
            "failedPattern": [
                "failed.*"
            ],
            "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",
            "weight": 1,
            "outputVariablesPrefix": "prefix:",
            "optional": false,
            "procName": "${instance-procNameVariable}",
            "title": "A step that runs a UNIX shell script.",
            "timeout": 60,
            "regionSize": 50000,
            "skills": "System Programmer",
            "output": null,
            "scriptParameters": "para1",
            "isRestStep": false,
            "saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
            "outputSysoutDD": null,
            "variable-specifications": [
                {
                    "scope": "instance",
                    "name": "st_group",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "st_user",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "procNameVariable",
                    "required": true
                }
            ],
            "name": "TSO-UNIX-shell_Execution",
            "successPattern": "success.*",
            "saveAsDataset": null
        },
        {
            "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            ",
            "instructions": "This step outputs some variables and prints a few words.\n        ",
            "autoEnable": "false",
            "maxLrecl": 1024,
            "submitAs": "TSO-UNIX-REXX",
            "failedPattern": [
                "failed.*"
            ],
            "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",
            "weight": 1,
            "outputVariablesPrefix": "prefix:",
            "optional": false,
            "procName": "${instance-procNameVariable}", 
            "title": "A step that runs a UNIX REXX exec program.",
            "timeout": 60,
            "regionSize": 50000,
            "skills": "System Programmer",

Figure 4. Sample response from a get workflow definition request (Part 3 of 3)


             "output": null,
            "scriptParameters": "para1",
            "isRestStep": false,
            "saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
            "outputSysoutDD": null,
            "variable-specifications": [
                {
                    "scope": "instance",
                    "name": "st_group",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "st_user",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "procNameVariable",
                    "required": true
                }
            ],
            "name": "TSO-UNIX-REXX_Execution",
            "successPattern": "success.*",
            "saveAsDataset": null
             },
             {
            "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            ",
            "instructions": "This step outputs some variables and prints a few words.\n        ",
            "autoEnable": "false",
            "maxLrecl": 1024,
            "submitAs": "TSO-REXX",
            "failedPattern": [
                "failed.*"
            ],
            "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",
            "weight": 1,
            "outputVariablesPrefix": "prefix:",
            "optional": false,
            "procName": "${instance-procNameVariable}",
            "title": "A step that runs a REXX exec program.",
            "timeout": 60,
            "regionSize": 50000,
            "skills": "System Programmer",
            "output": null,
            "scriptParameters": "para1",
            "isRestStep": false,
            "saveAsUnixFile": "/u/${instance-st_user}/savedStuff/myScript.sh",
            "outputSysoutDD": null,
            "variable-specifications": [
                {
                    "scope": "instance",
                    "name": "st_group",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "st_user",
                    "required": true
                },
                {
                    "scope": "instance",
                    "name": "procNameVariable",
                    "required": true
                }
            ],
            "name": "TSO-TSO-REXX_Execution",
            "successPattern": "success.*",
            "saveAsDataset": null
        }
    ],
    "productName": "Product ABC",
    "globalVariableGroup": null,
    "containsParallelSteps": false,
    "workflowDefinitionFileMD5Value": "5c5dd66eb3ca3cd1c578ccf323d57cc0",
    "isCallable": null,
    "productVersion": "Version 1",
    "jobsOutputDirectory": null,
    "vendor": "IBM",
    "scope": "none",
    "workflowVersion": "1.0",
    "category": "configuration",
    "workflowID": "programExecutionSample"
}