The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter contains the following sections:
Cisco UCS Director contains web-based documentation on all predefined tasks. To view the documentation, do the following:
Creating a workflow can be broken down into five overall steps:
Define the workflow. To define a workflow, you name the workflow and select a few other details.
Define the workflow inputs and outputs. You specify which input parameters the workflow requires to execute, and what output results from its execution.
Once the workflow inputs and outputs are defined, use the Workflow Designer to add a workflow task to the workflow.
Still in the Workflow Designer, connect the task into the workflow. Repeat these two steps, defining and adding a task, until you have incorporated all the tasks needed for the workflow to carry out its function.
Validate the workflow. Validating a workflow ensures that there are no errors in connecting task inputs and outputs.
These five steps are described in the following sections.
To define a workflow, do the following:
Step 1 | Navigate to . | ||||||||||||||||||||||||||||
Step 2 | Click the Workflows tab. | ||||||||||||||||||||||||||||
Step 3 | Click the Add action. | ||||||||||||||||||||||||||||
Step 4 | In the
Add
Workflow Details screen, complete the following fields:
|
Click Next to define input and output for the workflow.
You can define a set of inputs for a workflow. You can assign values for these inputs or restrict the values available to users at runtime. You can also choose whether to allow the user to change the administrator values at runtime.
To define workflow inputs and outputs, complete the following steps.
Define the workflow in the Workflow Add Details screen as described in the previous topic.
Step 1 | You can define
any number of inputs for a workflow.
Rather than define inputs for a workflow, you can instead associate the workflow with an activity and use the activity's inputs as the workflow's inputs; see Activities.
|
Step 2 | Click Next. |
Step 3 | To enter outputs
for the workflow, do the following.
|
Step 4 | Click Submit. The new workflow opens in the Workflow Designer. |
Add tasks to the workflow using the Workflow Designer. See Configuring a Task in a Workflow.
When you create a workflow, you can limit the set of entries from a table or list of values seen by the user at run time. You do this by either choosing the values explicitly using an Admin Input List, or by using a filter expression (Admin Input Filter). This section describes the syntax for writing admin input filters.
There are two types of data in Cisco UCS Director Orchestrator that you can filter:
Tabular data—A table with two or more columns. You filter the columns to choose the rows to display.
Lists of values (LOVs)—A list of items, all of the same type. You filter the values in the list.
In addition, some inputs are numeric, for example, disk storage sizes. You must include units when you filter numeric inputs.
To filter a tabular input, the input filter criteria have this form:
column_label operator expression [ AND column_label operator expression ]
where the elements of the expression are defined as follows:
Field | Entry |
---|---|
column_label |
The label at the top of the column to be filtered. Type the name exactly as it appears. The label is case-sensitive and must include any spaces or special characters. Do not enclose the label in quotes. |
operator |
One of: The operator name is case-sensitive; it must be all uppercase. IS_SUBSET and NOT_SUBSET are operators for list type inputs. |
[ ] (brackets) |
The brackets denote that the enclosed expression is optional and can be repeated. Do not include the brackets themselves in the filter criteria expression. |
AND |
Indicates extra criteria to be met. If one or more AND criteria are appended, all of them must be met to match a record. The criteria are applied serially. All records that meet the first criterion are subjected to the second criterion, then those results to the third, and so on. No operators besides AND can be used to append extra criteria. In particular, OR cannot be used. In other words, more criteria can be used only to narrow the search further, not to expand it. |
expression |
The syntax for expression is: match_expression [ OR match_expression ] |
OR |
Indicates a union of any of the specified match_expressions. In other words, only one of the match_expressions has meet the criterion for that part of the expression to be true. |
match_expression |
A simple regular expression that uses a subset of standard wildcard search characters and escape characters. The full POSIX regular expression syntax is not supported. You can match literal values provided they do not contain regex special characters or that you escape the special characters. For more information about regular expressions, consult any regular expression reference on the Internet; there are many. If match_expression is enclosed in quotes, a case-sensitive comparison is made, if applicable. |
Following is an example of a table-type filter:
Cloud CONTAINS vcenter21 OR vcenter98 AND Power Status EQUALS off OR unknown
The expression Cloud CONTAINS vcenter21 OR vcenter98 matches names containing vcenter21 and vcenter98, such as vcenter211 and TESTvcenter98. If you are interested only in vcenter21 and vcenter98, a better expression is Cloud EQUALS vcenter21 OR vcenter98.
LOV types are lists of single values. To filter an LOV you therefore omit the column name and the AND operator. The top-level search syntax is:
operator match_expression [ OR match_expression ]
The elements of the syntax are as described for tabular data, with the exception that IS_SUBSET and NOT_SUBSET operators are not permitted.
For example, if the power status values from the tabular data example were in an LOV, the search would look like this:
EQUALS off OR unknown
Certain numeric data such as disk size, LUN size, and volume size are specified with units--megabytes (MB), gigabytes (GB), or terabytes (TB). If the units are given in a table column, the units are part of the column label and must be included in your criteria; for example:
LUN Size (GB) EQUALS 10.0
Numeric expressions in filter criteria are regex matches and not numerical comparisons. For example, consider this filter criterion:
LUN Size (GB) EQUALS 10
The expression does not match records with LUN size given as 10.0.
Cisco UCS Director Orchestrator contains predefined tasks that you can use to create workflows. These tasks are organized in folders based on their functionality and can be accessed in the left panel of the Workflow Designer interface.
Documentation for the predefined tasks is available by opening the Task Library; see Viewing the Task Library.
Note | Cisco UCS Director Orchestrator's predefined tasks cover many if not most of the common operations required in a typical environment. For operations not represented in the predefined tasks, you can create custom tasks. See the Cisco UCS Director Custom Task Getting Started Guide. To configure a predefined task for use in a workflow, do the following: |
Define a workflow and its inputs and outputs as described in the previous sections.
Step 1 | From the Workflows tab on the Orchestrator page, choose a workflow. | ||||||||||||||||||
Step 2 | Click Workflow Designer. The Cisco UCS Director Orchestrator Workflow Designer window appears. | ||||||||||||||||||
Step 3 | On the left side of the Workflow Designer, choose a category from the Available Tasks area by expanding folders in the task hierarchy. | ||||||||||||||||||
Step 4 | Drag and drop your chosen task onto the Workflow Designer area. | ||||||||||||||||||
Step 5 | In the
Task
Information screen, complete the following fields:
| ||||||||||||||||||
Step 6 | Click Next. | ||||||||||||||||||
Step 7 | In the
User
Input Mapping screen, complete the following fields:
| ||||||||||||||||||
Step 8 | Click Next. | ||||||||||||||||||
Step 9 | Any task input
that was not mapped to a user input cannot be entered at runtime. Instead,
specify the input value now. In the
Task
Inputs screen, complete the following fields:
| ||||||||||||||||||
Step 10 | Click Next. | ||||||||||||||||||
Step 11 | In the
User
Output Mapping screen, complete the following fields:
| ||||||||||||||||||
Step 12 | Click Submit. If this is the first task configured in this workflow, the Workflow Designer automatically connects it to the default tasks. If the task is not the first, you must connect it manually. |
Connect the task to the workflow.
To be part of a workflow, a task must be connected to other tasks. You can insert a task anywhere in a workflow by dragging and dropping the flow arrows between tasks.
There are three default tasks in every workflow: Start, Completed (Success), and Completed (Failure). When you add the first task to a workflow, it automatically connects to the default tasks.
You have created a task in the Workflow Designer. The task is not yet part of the workflow.
Step 1 | Connect a task
from the existing workflow to the new task. To connect the tasks:
| ||||
Step 2 | Similarly, drag and drop from the On success drop-down of the new task to Completed (Success) or to another existing task in the workflow. | ||||
Step 3 | Drag and drop from the On failure drop-down of the new task to Completed (Failure) or to another existing task in the workflow. |
The task is integrated into the workflow. The Workflow Designer automatically arranges the tasks in the workspace.
Note | You can disable the automatic arrangement of the workflow by unchecking the Auto Layout check box at the top of the Workflow Designer. |
Add more tasks if necessary to complete the workflow. When you are finished, validate the workflow.
Validating a workflow ensures that the inputs and outputs of its component tasks are connected with no major errors. You can validate a workflow without leaving the Workflow Designer.
A workflow is open in the Workflow Designer.
If connection errors are displayed in the Workflow Designer, use the Workflow Validation tool to resolve the issues. See Resolving Workflow Validation Issues.
This simple example walks you through the creation of a workflow that power cycles (turns off and back on) a VM.
You must have a VM available in Cisco UCS Director.
Step 1 | Define the
workflow. Do the following:
| ||
Step 2 | Define an input
to specify the name of the VM. Do the following:
| ||
Step 3 | Do not define
an output. Click
Submit.
The Workflow Designer window appears. | ||
Step 4 | Add a task to
power off the VM by doing the following:
| ||
Step 5 | Add a task to
power on the VM. The procedure is similar to the previous step, with the
following differences:
| ||
Step 6 | Validate the workflow by clicking Validate Workflow button at the top of the Workflow Designer. The Valid Workflow dialog comes up, confirming that the workflow and task inputs and outputs are connected properly. | ||
Step 7 | Click Close to leave the Workflow Designer. |
Cisco UCS Director supplies a wizard-based tool to aid you in troubleshooting workflow validation errors.
A workflow has failed validation in the Workflow Designer.
Step 1 | On the menu bar, choose . |
Step 2 | Click the Workflows tab. |
Step 3 | Choose the workflow that failed validation. |
Step 4 | Click Validate Workflow. |
Step 5 | In the Workflow Validation dialog box, double click the description under Resolution. |
Step 6 | In the Validation Errors dialog box, view the summary for the issue detected. Complete the remaining prompts in the wizard to resolve the validation error. |
Normally, a workflow executes as a linear series of tasks. However, Cisco UCS Director Orchestrator provides tasks that enable changes to the flow of control within a workflow. The following sections describe how to create these flow-of-control constructs:
You can create a loop to perform a selected series of tasks multiple times. A loop can be configured to iterate one of two ways:
Open a workflow in which you want to include a loop in the Workflow Designer.
Step 1 | In the Available Tasks pane of the Workflow Designer, click the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the Start Loop task into the Workflow Designer work area. | ||||||||||||
Step 3 | In the
Add
Task window, complete the following fields:
| ||||||||||||
Step 4 | Click Next. | ||||||||||||
Step 5 | In the User Input Mapping screen, click Next. | ||||||||||||
Step 6 | In the
Task
Inputs screen, complete the following fields:
| ||||||||||||
Step 7 | In the User Output Mapping screen, click Submit. | ||||||||||||
Step 8 | From the Available Tasks pane, drag the tasks that you want as part of the loop. | ||||||||||||
Step 9 | Create links between the task icons in the loop using the On Success connector. | ||||||||||||
Step 10 | Create a link between the Start task icon (or whichever task is immediately before the loop) and the Start Loop task icon. | ||||||||||||
Step 11 | In the Available Tasks pane, click the Procedural Tasks folder. | ||||||||||||
Step 12 | Drag the End Loop task into the Workflow Designer. | ||||||||||||
Step 13 | Complete the remaining screens in the Add Task (End Loop) wizard. | ||||||||||||
Step 14 | Click Submit. | ||||||||||||
Step 15 | Connect the On Success connector of the last task in the loop to the End Loop task icon. | ||||||||||||
Step 16 | In the End Loop task icon, connect the On Success connector to the Completed (Success) or to another task to execute after the loop. | ||||||||||||
Step 17 | In the End Loop task icon, connect the On Failure connection to the Completed (Failure) (or another task) task icon. |
This example demonstrates repeating workflow tasks for elements in a list. You will modify the PowerCycleVM workflow to restart a list of VMs instead of a single VM.
Create the example workflow as described in Example: Creating a Workflow.
Step 1 | Open the
PowerCycleVM workflow.
|
Step 2 | Add the
Start
Loop task to the workflow.
|
Step 3 | The End Loop
task is just a placeholder with no inputs or outputs. To add the
End
Loop task to the workflow, do the following:
|
Step 4 | Click Close to close the Workflow Designer. |
Execute the task to restart the VMs specified in the workflow.
You can create a two-way branch in a workflow using an if-then construct.
You have a workflow open in the Workflow Designer.
Step 1 | In the Available Tasks pane of the Workflow Designer, click the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the If Else task into the Workflow Designer work area. | ||||||||||||
Step 3 | In the
Add
Task screen, complete the following fields:
| ||||||||||||
Step 4 | Click Next. | ||||||||||||
Step 5 | In the User Input Mapping screen, click Next. | ||||||||||||
Step 6 | In the
Task
Inputs screen, complete the following fields:
| ||||||||||||
Step 7 | In the User Output Mapping screen, click Submit. | ||||||||||||
Step 8 | In the If-Else task icon, click and drag the True connector and the False connector to other task icons. | ||||||||||||
Step 9 | In the
If-Else task icon, click and drag the
On
Failure connector to the
Completed (Failed) task icon (or another task icon).
|
You can create a multiple-path branch in a workflow using a conditional construct. A single conditional task can have any number of branches.
You have a workflow open in the Workflow Designer.
Step 1 | In the Available Tasks pane of the Workflow Designer, click the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the Conditional task intoWorkflow Designer work area. | ||||||||||||
Step 3 | In the
Add
Task screen, complete the following fields:
| ||||||||||||
Step 4 | Click Next. | ||||||||||||
Step 5 | In the User Input Mapping screen, click Next. | ||||||||||||
Step 6 | In the
Task
Inputs screen, click the + icon to add a condition statement for
each execution path of the workflow. For example, if your workflow has three
possible execution paths, add three entries into the conditions table, one
entry for each condition. Click the default entry in the table to specify the
condition when the workflow takes the default execution path.
| ||||||||||||
Step 7 | In the
Add
Entry to screen, complete the following fields:
Click Submit. | ||||||||||||
Step 8 | In the User Output Mapping screen, click Submit. | ||||||||||||
Step 9 | From the Available Tasks pane, click and drag the tasks that you want to add to the various execution paths of the workflow. | ||||||||||||
Step 10 | Create a link between the Start task icon (or whichever task is immediately before the branch) and the Conditional task icon. | ||||||||||||
Step 11 | For each condition in the conditional task, create a link between the connector in the Conditional Task icon to the next task for the condition's execution path. For example, link the default connector in the Conditional task icon to the task you want to execute if none of the other conditions are met. | ||||||||||||
Step 12 | Link the On failure connector to the Completed (Failed) (or another task) task icon. |
To require approval of a user, you add an approval task to the workflow.
Open a workflow in the Workflow Designer.
Step 1 | In the Workflow Designer Available Tasks window, open . | ||||||||||||||||||||||||||||||||
Step 2 | Drag the User Approval task onto the work area. | ||||||||||||||||||||||||||||||||
Step 3 | Configure the
task. See
Configuring a Task in a Workflow.
Complete the following fields:
| ||||||||||||||||||||||||||||||||
Step 4 | Click Next. | ||||||||||||||||||||||||||||||||
Step 5 | In the User Input Mappings click Next. You define all the task inputs in the Task Inputs window. | ||||||||||||||||||||||||||||||||
Step 6 | In the Task Inputs window, complete the following fields:. | ||||||||||||||||||||||||||||||||
Step 7 |
| ||||||||||||||||||||||||||||||||
Step 8 | Click Next. | ||||||||||||||||||||||||||||||||
Step 9 | In the User Output Mapping window, click Submit. |