Start a workflow

You can use this operation to start a z/OSMF workflow on a z/OS system. The workflow to be started must contain at least one automated step.

HTTP method and URI path

PUT /zosmf/workflow/rest/<version>/workflows/<workflowKey>/operations/start
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 workflow to be started.

Query parameters

None.

Description

This operation is used to start an automated workflow, that is, a workflow with at least one step that can be performed automatically. For information about designing an automated workflow, see Automated steps.

On successful completion, HTTP status code 202 (Accepted) is returned. If you specify a notification URL in your request, a JSON object is posted to the URL when automation stops; the format of the object is described in Content that is posted to the notification URL.

This request must be submitted from the user ID of the step owner for the automated step. Otherwise, the request ends with HTTP status code 400 and an error message. Also, if used with a workflow that contains no automated steps, the request ends with HTTP status code 400 and an error message.

Parallel-steps workflows

A workflow with steps that can be run in parallel (concurrently) is called a parallel-steps workflow. When you start a parallel-steps workflow, the Workflows task locates the automation ready steps and attempts to run them concurrently.

A step is considered to be automation ready when it is:
  • Enabled for automation. In the workflow definition file, the attribute autoEnable=true is specified on the step element (<step>).
  • In an eligible state: ready, in-progress, or failed. For a failed step, the Workflows task performs the step again.

To use parallel processing, an automated workflow must include the attribute parallelSteps=true in the workflow metadata. Otherwise, if this attribute is set to false or omitted, 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.

In a parallel-steps workflow, the failure of an automated step does not stop automation processing for the other automated steps. Processing continues until all of the automated steps are completed or failed, or a condition occurs that stops automation processing, such as a user stopping automation by using the Stop Automation action in the Workflows task.

Note: The ability to suspend step processing is mutually exclusive with the ability to run steps in parallel. Therefore, if a workflow includes the suspend element (<suspend>) in the step definition, it is not eligible for parallel processing. The Workflows task enforces this restriction. An attempt to start a workflow that contains both the suspend element (<suspend>) and the attribute parallelSteps=true will result in an error.

Request content

Your request can contain a JSON object that specifies options for starting the workflow. The request content is optional; it can be omitted or be empty. If so, default values are used for any optional properties that can be specified.

Table 1 lists the fields in the JSON object.
Table 1. Request content for the start workflow request
Field name Type Required or optional Description
resolveConflictByUsing String Optional Indicates how variable conflicts, if any, are to be handled when the Workflows task reads in the output file from a step that runs a REXX exec or UNIX shell script.
The following values are valid for this parameter:
outputFileValue
Allow the output file values to override the existing values. This setting applies to instance variables only; global variables are not overridden by variables in the output file.
existingValue
Use the existing variables values instead of the output file values.
leaveConflict
Automation is stopped. The user must resolve the conflict manually.

If you omit this property, the default is outputFileValue.
stepName String Optional The name of the step at which automation is to begin. If you omit this property, automation processing begins with the first step in the workflow.

In a parallel-steps workflow, the automation ready steps are processed in an unpredictable order, not sequentially as is done for other types of workflows. Therefore, automation cannot be directed to start at a specific step. If you specify this property for a parallel-steps workflow, the property is accepted but ignored.
performSubsequent Boolean Optional If the workflow contains any subsequent automated steps, this property indicates whether z/OSMF is to perform the steps. If you set this property to true, or omit the property, z/OSMF attempts to perform the automated steps. If you set this property to false, z/OSMF attempts to perform the specified step only. The default is true.

In a parallel-steps workflow, the automation ready steps are processed in an unpredictable order, not sequentially as is done for other types of workflows. Therefore, automation cannot be directed to start at a specific step. If you specify this property for a parallel-steps workflow, the property is accepted but ignored.
notificationUrl String Optional A notification URL (up to 2000 characters).

Depending on the requirements of your application, you might want to receive a notification when the automated step or steps reach an end state (either completion or failure). Suppose, for example, that your application includes a servlet that is to be given control on completion of the automated steps. If so, you can optionally specify a notification URL to be posted when automation ends.

Your installation must add this URL to the list of allowable sites. Work with your security administrator to create the appropriate authorization; see Allowing cross-site access to REST services.

If specified, this URL receives a JSON object with the result of the automation processing. For the format of the JSON object, see Table 3.
targetSystemuid String Optional The user ID to be used for remote system basic authentication.
targetSystempwd String Optional The password to be used for remote system basic authentication.

Authorization requirements

See Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 202 (Accepted) is returned.

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 2. HTTP error response codes for a start workflow request
HTTP error status code Description
HTTP 400 Bad request The request contained incorrect parameters. For example:
  • Incorrect value is specified for the property resolveConflictByUsing.
  • Specified workflow contains no automated steps.
  • Request is submitted from a user ID that is not the step owner for the automated step. For a parallel-steps workflow, the request is submitted from a user ID that is not the step owner for any of the automated steps in the workflow.
  • Automation processing attempts to begin at a step that is not automated.
  • Incorrect value is specified for the property stepName.
HTTP 404 Not found The specified workflow key was not found; the workflow does not exist.
HTTP 409 Request conflict Request cannot be performed automatically because the specified workflow has one of the following statuses:
  • Automation-in-progress
  • Canceled
  • Complete (for a parallel-steps workflow). A start request is not applicable for a parallel-steps workflow that is complete.
HTTP 500 Internal server error The server encountered an error. See the response body for a JSON object with information about the error.

Additional standard status codes can be returned, as described in HTTP status codes.

Content that is posted to the notification URL

If you specified a notification URL in your request, the URL receives a JSON object when automation stops. Table 3 lists the fields in the JSON object.
Table 3. Structure of the JSON object that is returned to the notification URL
Field name Type Description
instanceURI String Specifies the URI path of the workflow that was being automated. You can use the URI path to retrieve more details about the workflow.
statusName String

Indicates the current workflow status after automation has stopped.

The following are the possible values that might be returned after a stopped automation:
in-progress
The workflow automation is stopped. The reason is indicated in the messageID and messageText properties.
complete
Workflow is complete. All steps are marked complete or skipped.
startUser String User ID of the user who initiated the automation processing.
startedTime Timestamp Time that automation processing started.
stopUser String User ID of the user who stopped automation.
stoppedTime Timestamp Time that automation processing stopped.
currentStepName String Name of the step that caused automation to stop. If the workflow status is complete, this property is set to null.
currentStepNumber String The step number. If the workflow status is complete, this property is set to null.
currentStepTitle String Step title. If the workflow status is complete, this property is set to null.
messageID String This property contains the message identifier that helps identify the reason that automation is stopped.
messageText String

This property contains the message text associated with the message identifier found in messageID.

Example HTTP interaction

In Figure 1, a request is submitted to start a workflow. Here, the workflow is identified by the workflow key, which is the following string value: d043b5f1-adab-48e7-b7c3-d41cd95fa4b0. In this example, the request content is empty. As a result, default values are used for any properties that can be specified; see Table 1.
Figure 1. Sample request to start a workflow
PUT /zosmf/workflow/rest/1.0/workflows/d043b5f1-adab-48e7-b7c3-d41cd95fa4b0/operations/start HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Content-Type: application/json
Content-Length: 3
Authorization: Basic em9zbWZhZDp6b3NtZmFk

{}
A sample response is shown in Figure 2.
Figure 2. Sample response from a start workflow request
HTTP/1.1 202 Accepted
content-length: 0
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
date: Wed, 11 Feb 2015 18:29:55 GMT
content-type: application/json; charset=UTF-8