Get the properties of an archived workflow

You can use this operation to retrieve the properties of an archived z/OSMF workflow.

HTTP method and URI path

GET /zosmf/workflow/rest/<version>/archivedworkflows/<workflowKey>

In this request, the URI path variables are described, as follows:

<version> identifies the version of the z/OSMF workflow service. The following value is valid: 1.0.
<workflowKey> identifies the archived workflow to be queried.

Query parameters

You can specify the following query parameter on this request:

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 5 lists the fields in the variable-info 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 properties of an archived 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 5.

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

Table 1. HTTP error response codes for a get archived workflow properties request
HTTP error status code	Description
`HTTP 400 Bad request`	The request contained an incorrect parameter, such as an incorrect workflow key.
`HTTP 403 Forbidden`	The requestor user ID is not permitted to retrieve the workflow properties.
`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.

Table 2. JSON object that is returned to a get archived workflow properties request
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, which is archived.
`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: If no automation was performed for the workflow, this property is null. If automation was restarted after being stopped previously, this property indicates the status of the current start automation request. If automation processing is still in progress, this property indicates which step is being processed. If automation is stopped and the workflow status is not complete, this property identifies the step most closely related to why automation was stopped. If automation is stopped and the workflow status is complete, this property indicates that automation is completed. Table 3 lists the fields in the automation-info object.
`access`	String	Specifies the access type for the workflow. The access type determines which users can view the workflow steps and edit the step notes, as described in Workflow access type. The following values are valid: `Public` `Restricted` `Private`
`archivedTime`	String	Date and time on the system when the workflow was archived. The date and time is in Greenwich Mean Time (GMT).
`accountInfo`	String	May be null, or the account information in the JCL JOB statement.
`jobStatement`	String	May be null, or a list of JCL cards, each up to 72 characters long.
`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

Table 3 lists the fields in the automation-info JSON object.

Table 3. Get Archived Workflow Properties request: 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

Table 4 lists the fields in the step-info JSON object. Not all of the properties are returned for every step. Some properties are returned or omitted depending on the step type, as noted in the When returned column. This information in this column indicates whether valid data is returned for the step, as follows:

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.

Table 4. Get Archived Workflow Properties request: Format of the step-info object
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: Is null when the property `calledWorkflowMD5` is specified Might be null when the property `calledWorkflowID` is specified.
`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: GET PUT POST DELETE
`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. `actualStatusCode` `expectedStatusCode` `hostname` `hostnameSub` `httpMethod` `port` `portSub` `queryParameters` `queryParametersSub` `requestBody` `requestBodySub` `schemeName` `schemeNameSub` `uriPath` `uriPathSub` The following step properties are not applicable for a REST step and thus, are omitted from the output: `template` `templateSub` `output` `outputSub` `saveAsDataset` `saveAsDatasetSub` `saveAsUnixFile` `saveAsUnixFileSub` `submitAs` `maxLrecl` `returnCode`
`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: Unassigned. The step is in the Unassigned state; no users or groups are assigned to the step. Assigned. Users or groups are assigned to the step, but no user accepted ownership of the step. Not Ready. A user accepted ownership of the step, however, a prerequisite step must be completed or a conditional dependency must be satisfied before the step can be performed. Ready. The step is ready to be performed; all prerequisite steps and conditional dependencies are satisfied. In Progress. The step is in progress. For a parent step, a state of In Progress means that at least one of the child steps is started, but is not yet complete, overridden, or skipped. For a leaf step, a state of In Progress means that the step is started, but is not yet complete, overridden, or skipped. Submitted. The step included a job, which the step owner submitted. Complete. The step was completed. Skipped. The step was bypassed by the step assignee. Complete (Override). The step was marked complete, but the work was performed outside of the Workflows task. Failed. The step included a job that was submitted by the step owner. However, the job failed to complete successfully. Conflicts. The step created an output file for use by a subsequent step. However, values in that file conflict with existing instance or global variables. Condition Not Satisfied. The step is a conditional step, and the condition is not satisfied.
`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: `“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 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

Table 5 lists the fields in the variable-reference JSON object.

Table 5. Get Archived Workflow Properties request: 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

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

Table 6. Get Archived Workflow Properties request: 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: boolean string number date time
`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 an archived workflow. The workflow is uniquely identified by the workflow key, which is represented by the following string value: 2535b19e-a8c3-4a52-9d77-e30bb920f912.

Figure 1. Sample request to get archived workflow properties

GET /zosmf/workflow/rest/1.0/archivedworkflows/2535b19e-a8c3-4a52-9d77-e30bb920f912
HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Authorization: Basic em9zbWZhZDp6b3NtZmFk

An example of the response is shown in Figure 2.

Figure 2. Sample response from a get archived workflow properties request

HTTP/1.1 200 OK
{
"percentComplete": 0,
"workflowDefinitionFileMD5Value":"6533178a155a98e784b056f0b16d060f",
"statusName": "archived",
"vendor": "IBM",
"accountInfo": null,
"workflowVersion": "1.0",
"automationStatus": null,
"access": "Public",
"productVersion": "Version 1",
"productID": "ABC123",
"category": "configuration",
"system": "DUMBPLEX.DUMBNODE (DUMBNODE)",
"workflowName": "Sample demonstrating variable substitution and the 
use of a wizard. - Workflow_5",
"workflowDescription": "Sample demonstrating variable substitution and the 
use of a wizard.",
"workflowID": "wizardSample",
"owner": "domadmin",
"jobStatement": null,
"workflowKey": "2535b19e-a8c3-4a52-9d77-e30bb920f912",
"productName": "Product ABC",
"archivedTime": "2016-10-11 09:28:33"
}