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.

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.
`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`.
`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.

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. 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.

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.
`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