Using the element atCreate to qualify a variable definition

This topic describes the element atCreate (<atCreate>). For users of the Create Workflow REST service, the atCreate element provides additional options for working with variables.

The Create Workflow REST service is described in Create a workflow.

The following attributes can be specified on the atCreate element:

name

Specifies the variable for which the variable attributes are being set. The name is required. For example, to set a variable named var1, define the atCreate element with the name var1.

scope

Specifies the scope of the variable. This value is set to instance (the only valid value) or is omitted; the default is instance.

required

This attribute has a specialized purpose. For a workflow that is created through the Create Workflow REST service, this attribute indicates whether the variable must be set to a value at the time of workflow creation. A variable can be set in any of the following ways:

Defining a default value for the variable in the workflow definition
Setting a value for the variable in the workflow variable input file
Specifying a value for the variable on a Create Workflow service.

This attribute is optional; the default is false. If a variable is marked as "required," but the variable is not given a value, an attempt to create the workflow through the Create Workflow REST service will fail with an error.

For a workflow that is created through the Workflows task user interface, this option is ignored. That is, the workflow is created, regardless of the setting of the required attribute.

Note: This setting is returned as the "requiredAtCreate" property of a variable by the Retrieve Workflow Definition service; See Retrieve a workflow definition.

prompt

For users of the Create Workflow REST service, this attribute identifies a variable that should be prompted for by the program that issues the REST service. By itself, the prompt attribute does not enforce any behavior for the workflow creation. However, by setting prompt to true, you can indicate that prompting is recommended for the variable. The user of the Create Workflow REST service can query the value of the prompt attribute for any variables in the workflow to determine whether any variables should be prompted for.

This attribute is optional; the default is false.

Note: This setting is returned as the "promptAtCreate" property of a variable by the Retrieve Workflow Definition service; See Retrieve a workflow definition.

You can specify the atCreate element for any instance variables that are used in a workflow definition. The atCreate element is not valid for global variables.

Example of using the element atCreate

Suppose that you have a variable that would be useful to include in a number of different workflows. If so, you can define the variable in an XML file (an XML fragment) and include the same fragment in the appropriate workflow definitions. The variable is now shared between these workflows.

In Figure 1, the variable variable_test is defined in an XML file. The variable is used by more than one workflow, so the variable definition is coded in an XML file that can be included with multiple workflows.

Figure 1. Variable definition in this example

<variable name="variable_test" scope="instance">
        <label>Variable 4</label>
        <abstract>Abstract for variable 4.</abstract>
        <description>Description for variable 4.</description>
        <category>variables</category>
        <string/>
    </variable>

Now suppose that the variable's attributes for required and prompt need to be set differently for different workflows. The atCreate (<atCreate>) element, which is used with the variable element, allows you to specify different prompt and required settings for the same variable in different workflow definitions. To do so, have each workflow definition include the XML file that defines the variable. Then, in each workflow definition, specify the atCreate element to further clarify the properties of the variable.

In Figure 2, the atCreate element is used to specify the attributes required and prompt for the variable variable_test, which was defined in Figure 1. The atCreate element can be defined differently in any workflow definition that refers to the variable variable_test.

Figure 2. How the atCreate element is used to specify variable attributes for required and prompt

<atCreate name="variable_test" required="true" prompt="true"/>

By including the atCreate element in each workflow definition, you can set different values for the prompt and required attributes for the same variable in different workflows.