Create a workflow

You can use this operation to create a z/OSMF workflow on a z/OS system.

HTTP method and URI path

POST /zosmf/workflow/rest/<version>/workflows

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

None.

Description

This operation creates a workflow, based on the properties that are specified in the request body (a JSON object). For the properties that you can specify, see Request content.

On successful completion, HTTP status code 201 (Created) is returned, indicating that the request resulted in the creation of a new workflow. The URI path for the workflow is provided in the Location response header and a response body is provided, as described in the Response content.

Workflow access type

By default, general information about the workflow and its steps can be viewed by all users of the Workflows task. If you want to restrict access to a workflow or portions of a workflow, you can do so by specifying an access type in the request body for your Create Workflow request. The access type determines which users can view the workflow steps and edit the step notes. The access type is specified on the accessType property.

The valid values for the accessType property are summarized, as follows:

Public: Information about the workflow, including the steps and notes, can be viewed by all users.
Restricted: Information about steps, variables, and notes, is restricted to a subset of users—the workflow owner, step owners, and step assignees. Other users cannot access this information.
Private: Information is restricted to a subset of users, and is further limited among these users. The workflow owner can access information about steps, variables, and notes. Step owners and assignees can retrieve information about the steps for which they are assigned or own, and the associated variables for those steps. Other users cannot access this information.

The accessType property is optional. If you omit it from the request body, the workflow is created with public access.

With the exception of workflow notes and step notes, this information is also available to REST API requestors through the Get Workflow Properties service. For the types of information that are restricted by access type, see Get the properties of a workflow.

Request content

The request content is expected to contain a JSON object that describes the workflow to be created. Table 1 lists the fields in the JSON object.

Table 1. Request content for the create workflow request
Field name	Type	Required or optional	Description
`workflowName`	String	Required	Descriptive name for the workflow (up to 100 characters). The name cannot contain the symbols for less-than (<), greater-than (>), or ampersand (&). z/OSMF validates this name to ensure that it is unique across all of the existing workflows.
`workflowDefinitionFile`	String	Required	Location of the workflow definition file. This file is the primary XML file for the workflow definition. Specify this value, as follows: If the workflow definition file resides in a data set member, specify the fully qualified data set name, including the member name. Ensure that this data set is cataloged. If the workflow definition file resides in a z/OS UNIX file, specify the fully qualified path name of the file, beginning with the forward slash (/) and including the file name. For example: /usr/lpp/zosmf/V2R1/samples/workflow_sample_automation.xml.
`variableInputFile`	String	Optional	Specifies an optional properties file that you can use to pre-specify values for one or more of the variables that are defined in the workflow definition file. Specify this property, as follows: If the workflow variable input file resides in a data set member, specify the fully qualified data set name, including the member name. Ensure that this data set is cataloged. If the workflow variable input file resides in a z/OS UNIX file, specify the fully qualified path name of the file, beginning with the forward slash (/) and including the file name. For the format of the contents of the variable input file, see Providing a workflow variable input file.
`variables`	Array of objects	Optional	A list of one or more variables for this workflow. The variables that you specify here take precedence over the variables that are specified in the workflow variable input file. Specify this property as an array of name-value objects, for example: `"variables": [ {"name":"user_name","value":"IBMUSER"}, {"name":"file_name","value":"textfile.txt"} ]`
`resolveGlobalConflictBy Using`	String	Optional	On creation of the workflow, z/OSMF determines whether any of the variables that are supplied in this request (through the variable input file or variables array) would conflict with existing global variables in the Workflows task. In such cases, this property specifies which version of the variable is used, as follows: When set to `input`, the global variable conflicts are overridden by the variables in specified input file. The global variable value is updated with the input variable value. Use caution with this setting; your selection will affect any other workflows that refer to the same global variable. When set to `global`, or omitted, the variable value supplied with the request (through the variable input file or variables array) is ignored and the current global value is used. The default is `global`.
`system`	String	Required	Nickname of the system on which the workflow is to be performed. 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. If the specified workflow definition file contains an immediate execution step (a template step that runs a program in real time), the workflow must be created on the local system. For information about immediate executions steps, see Template steps.
`owner`	String	Required	User ID of the workflow owner. This user can perform the workflow steps or delegate the steps to other users. Specify a valid user ID, as it is defined to your installation's z/OS security management product, such as RACF. A valid user ID consists of one to eight alphanumeric characters (A-Z, a-z, 0-9, #, $, and @).
`comments`	String	Optional	Specifies any information that you want to associate with the creation of this workflow (up to 500 characters). This information is recorded in the workflow history. Consider including a meaningful comment on the workflow, for example: `This workflow was created through the z/OSMF workflow services REST interface.`
`assignToOwner`	Boolean	Optional	Indicates whether the workflow steps are assigned to the workflow owner when the workflow is created. If you set this property to true, or omit the property, z/OSMF assigns the steps to the user ID that is specified on the property `owner`. If you set this property to false, the workflow steps are left unassigned when the workflow is created. The default is `true`.
`accessType`	String	Optional	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` If you omit this property, the workflow is `public`, by default.

Authorization requirements

See Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided, as described in Response content.

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 create workflow request
HTTP error status code	Description
`HTTP 400 Bad request`	The request contained incorrect parameters. For example: The specified workflow name contains errors or is not unique. Workflow definition file contains errors or does not exist. Variable input file does not exist. A validation error occurred for one or more of the following properties: `variables`, `system`, `owner`, or `comments`. An incorrect value is specified for the property `resolveGlobalConflictByUsing`.
`HTTP 403 Forbidden`	The requestor user ID is not permitted to the workflow definition file or the variable input file.

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

Response content

On successful completion, the service returns the following:

URI path of the created workflow in the Location response header.
Response body, which contains a JSON object with details about the workflow. Table 3 lists the fields in the JSON object.

Table 3. Response from a create workflow request
Field name	Type	Description
`workflowKey`	String	Workflow key. A string value, which is generated by z/OSMF to uniquely identify the workflow instance.
`workflowDescription`	String	Workflow description. This value is obtained from the element `workflowDescription` in the workflow definition file.
`workflowID`	String	Workflow ID. A short, arbitrary value that identifies the workflow. This value is obtained from the element `workflowID` in the workflow definition file.
`workflowVersion`	String	Version of the workflow definition file. This value is obtained from the element `workflowVersion` in the workflow definition file.
`vendor`	String	Name of the vendor that provided the workflow definition file. This value is obtained from the element `vendor` in the workflow definition file.

Example HTTP interaction

In Figure 1, a request is submitted to create the workflow AutomationExample on the system SY1.

Figure 1. Sample request to create a workflow

POST /zosmf/workflow/rest/1.0/workflows HTTP/1.1
Host: zosmf1.yourco.com
Connection: close
Content-Type: application/json
Content-Length: 203
Authorization: Basic em9zbWZhZDp6b3NtZmFk

{
    "workflowName":"AutomationExample",
    "workflowDefinitionFile":"/usr/lpp/zosmf/V2R1/samples/workflow_sample_automation.xml",
    "system":"SY1",
    "owner":"zosmfad",
    "assignToOwner":true,
    "accessType": "Restricted"
}

A sample response is shown in Figure 2.

Figure 2. Sample response from a create workflow request

HTTP/1.1 201 Created
content-length: 210
content-language: en-US
x-powered-by: Servlet/3.0
server: WebSphere Application Server
connection: Close
location: /zosmf/workflow/rest/1.0/workflows/d043b5f1-adab-48e7-b7c3-d41cd95fa4b0
date: Wed, 11 Feb 2015 18:29:55 GMT
content-type: application/json; charset=UTF-8

{
    "vendor": "IBM", 
    "workflowDescription": "Sample demonstrating the use of automated steps in workflow.", 
    "workflowID": "automationSample", 
    "workflowKey": "d043b5f1-adab-48e7-b7c3-d41cd95fa4b0", 
    "workflowVersion": "1.0"
}