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

Except for 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/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 a list of name-value objects, for example: 
"variables":
 [
  {"name":"user_name","value":"IBMUSER"},
  {"name":"file_name","value":"textfile.txt"}
 ]
If you plan to include an array type variable on the variables property, specify the variable as a list of strings, with each string separated by the following escape character: \. In the following example, the variable array3 is an array variable: 

 "variables": 
 [{"name":"user_name","value":"IBMUSER",}
  {"name":"file_name","value":"textfile.txt"},
  {"name": "array3", "value": clust
         "[ \"ZOSV23T\", \"DB211T\",
           {\"property1\":\"tt1\",
            \"dsname\":\"TEST.DSNAME.TT1\"}]"}]

For more information about array variables, see Array variables.
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 affects any other workflows that refer to the same global variable.
  • When set to global, or omitted, the variable value that is 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 created. 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.
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.

accountInfo String Optional For a workflow that submits a job, this property specifies the account information to use in the JCL JOB statement. This property can be null.
jobStatement String Optional For a workflow that submits a job, this property specifies the JOB statement JCL that is used in the job. This property can be null, or a list of JCL cards, each up to 72 characters long. Columns 1 and 2 of each record must be "//" or "/*" and the job name must be 1 to 8 characters.
deleteCompletedJobs Boolean Optional For a workflow that submits a job, this property specifies whether the job is deleted from the JES spool after it completes successfully. To retain the job, set this property to false, which is the default. If so, the job remains on the JES spool until it is removed by a user or automated process. To conserve space in the JES spool, consider setting this property to true.

If you omit this property, the completed job is retained on the JES spool.

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 with 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.
  • Validation error. The specified value does not match the validation criteria 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/samples/workflow_sample_automation.xml",
    "system":"SY1",
    "owner":"zosmfad",
    "assignToOwner" :true,
    "accessType": "Restricted",
    "deleteCompletedJobs" : true
}
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"
}