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:
The Workflow Designer is a graphical tool for building workflows. In the Workflow Designer, you add and arrange tasks to build up a workflow. Following is a brief description of the parts of the Workflow Designer.
To bring up the Workflow Designer:
Select a workflow from the Workflow report or create a new workflow. See Defining a Workflow.
From the More Actions drop-down list, choose Workflow Designer.
On the Workflow Designer screen, observe the following components:
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 | Choose Orchestration. | ||||||||||||||||||||||||||||
Step 2 | On the Orchestration page, click Workflows. | ||||||||||||||||||||||||||||
Step 3 | Click Add (+). | ||||||||||||||||||||||||||||
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 a selected predefined task appears at the bottom of the task list in the Workflow Designer. To expand the documentation and open the entire Task Library in your browser, click Read More … at the bottom left of the Workflow Designer. 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 | Choose Orchestration. | ||||||||||||||||||
Step 2 | On the Orchestration page, click Workflows. | ||||||||||||||||||
Step 3 | Choose a workflow. | ||||||||||||||||||
Step 4 | Click Workflow Designer. The Cisco UCS Director Orchestrator Workflow Designer screen appears. | ||||||||||||||||||
Step 5 | On the left side of the Workflow Designer, choose a category from the Available Tasks area by expanding folders in the task hierarchy. | ||||||||||||||||||
Step 6 | Drag and drop your chosen task onto the Workflow Designer work area on the right side of the screen. | ||||||||||||||||||
Step 7 | On the Task Information screen, complete the following fields:
| ||||||||||||||||||
Step 8 | Click Next. | ||||||||||||||||||
Step 9 | On the User Input Mapping screen, complete the following fields:
| ||||||||||||||||||
Step 10 | Click Next. | ||||||||||||||||||
Step 11 | Any task input that was not mapped to a user input cannot be entered at runtime. Instead, specify the input value now. On the Task Inputs screen, complete the following fields:
| ||||||||||||||||||
Step 12 | Click Next. | ||||||||||||||||||
Step 13 | On the User Output Mapping screen, complete the following fields:
| ||||||||||||||||||
Step 14 | 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 (Failed). 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 in the Workflow Designer work area but 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 connector of the new task to Completed (Success) or to another existing task in the workflow. | ||||||
Step 3 | Drag and drop from the On failure connector of the new task to Completed (Failed) or to another existing task in the workflow. |
The task is connected into the workflow.
Note | Click Auto Layout at the top right of the Workflow Designer to arrange the workflow tasks in the work area with uniform spacing and alignment. |
Note | To delete a task from the workflow, mouse over the workflow and click the red Delete (X) icon that appears. |
Add more tasks if necessary to complete the workflow. When you are finished, validate the workflow. See Validating a 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.
Open a workflow 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 have a virtual machine (VM) 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 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. The system displays the message This workflow is valid, confirming that the workflow and task inputs and outputs are connected properly. | ||
Step 7 | Click the Close Screen control in the upper right 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 | Choose Orchestration. |
Step 2 | On the Orchestration page, click Workflows. |
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 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:
Note | Conditional tasks, including Conditional Task and If Else, are denoted in the Workflow Designer with a diamond icon in their upper left corner. See The Workflow Designer. |
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 Available Tasks area in the Workflow Designer, open the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the Start Loop 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 | On the User Output Mapping screen, click Submit. | ||||||||||||
Step 8 | From the Available Tasks area, drag the tasks that you want as part of the loop into the work area of the Workflow Designer. | ||||||||||||
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 theAvailable Tasks area in the Workflow Designer, click the Procedural Tasks folder. | ||||||||||||
Step 12 | Drag the End Loop task into the Workflow Designer work area. | ||||||||||||
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 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 (Failed) (or another task) task icon. |
This example demonstrates how to repeat 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 area of the Workflow Designer, open the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the If Else task into the Workflow Designer work area. | ||||||||||||
Step 3 | On the Add Task screen, complete the following fields:
| ||||||||||||
Step 4 | Click Next. | ||||||||||||
Step 5 | On the User Input Mapping screen, click Next. | ||||||||||||
Step 6 | On the Task Inputs screen, complete the following fields:
| ||||||||||||
Step 7 | On 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 area of the Workflow Designer, expand 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, 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 area, 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. |
You can lock a named resource to prevent other tasks from accessing that resource. To lock a resource, you acquire a lock on a resource name in a workflow and release the lock later in the same workflow. While the workflow holds the lock, other service requests (Workflows) block until the workflow that is currently holding the resource lock releases the lock.
Note | The resource name is a generic character string with no programmatic connection to the resource being accessed. The Acquire Lock on a Named Resource task blocks workflow execution based only on the name of the resource that you specify. For purposes of locking, you can name a resource anything, but we recommend that you use the name of the resource as shown in Cisco UCS Director. The name is unique, can be looked up easily, and is difficult to mistakenly assign to the wrong resource. |
A workflow (within a single service request) can acquire a lock multiple times (this is called reentrant locking). If a workflow task has acquired a lock, then a successive attempt by any task in the workflow to acquire the same lock also succeeds. A lock acquired multiple times within a workflow must be released the same number of times before the resource name is free.
A compound task (see Creating a Compound Task) always succeeds in acquiring a lock if that lock is already held by its parent workflow.
Open a workflow containing a reference to a resource that you want to lock.
Step 1 | In theAvailable Tasks area in the Workflow Designer, open the Procedural Tasks folder. | ||||||||||||
Step 2 | Drag the Acquire Lock on a Named Resource task into the Workflow Designer work area. | ||||||||||||
Step 3 | In the Add Task screen, complete the following fields:
| ||||||||||||
Step 4 | Click Next. | ||||||||||||
Step 5 | On the User Input Mapping screen, click Next. | ||||||||||||
Step 6 | On the Task Inputs screen, enter the name of the resource you want to lock.
| ||||||||||||
Step 7 | On the User Output Mapping screen, click Submit. | ||||||||||||
Step 8 | Create a link between the task immediately before the resource lock and the Acquire Lock on a Named Resource task icon. | ||||||||||||
Step 9 | From the Available Tasks area, drag the task that you want within the duration of the resource lock into the work area of the Workflow Designer. | ||||||||||||
Step 10 | Complete the Add Task wizard for the new task. | ||||||||||||
Step 11 | Link the task within the lock duration into the workflow using the On Success connector. | ||||||||||||
Step 12 | Repeat steps 9 to 11 if there are more tasks that you want to include in the duration of the resource lock. | ||||||||||||
Step 13 | In theAvailable Tasks area in the Workflow Designer, click the Procedural Tasks folder. | ||||||||||||
Step 14 | Drag the Release Lock on a Named Resource task into the Workflow Designer work area.
| ||||||||||||
Step 15 | Complete the Task Information screen as you did in step 3. | ||||||||||||
Step 16 | Click past the User Input Mapping screen. | ||||||||||||
Step 17 | On the Task Inputs screen, enter the name of the locked resource. | ||||||||||||
Step 18 | Click Next. | ||||||||||||
Step 19 | Click Submit. | ||||||||||||
Step 20 | Connect the On Success connector of the last task added to the workflow to the Release Lock on a Named Resource task icon. | ||||||||||||
Step 21 | In the Release Lock on a Named Resource task icon, connect the On Success connector to the next task in the workflow. | ||||||||||||
Step 22 | In the Release Lock on a Named Resource task icon, connect the On Failure connection to the Completed (Failed) (or another task) task icon. |
You can upload files to Cisco UCS Director. The file is made available to the workflow task. To upload a file, you set an input to the File Upload input type.
Note | Cisco UCS Director does not perform any validation of the contents of the file nor performs scans for viruses and malware. Extreme caution must be exercised to prevent virus infected files from being uploaded. |
The file to upload must meet the following specifications:
The file size is less than 100 MB.
The file is in zip format.
If a task has a user input of type File Upload, then either a File Upload or Generic Text input can be mapped to it.
Uploaded files should not be deleted by tasks because the file may be used in other workflows or in subsequent tasks within the same workflow.
The behavior of the system with respect to the file is different depending on the source of the input:
To upload a file to Cisco UCS Director and make it available in a workflow, follow these steps:
Step 1 | Choose Orchestration. | ||
Step 2 | On the Orchestration page, click Workflows. | ||
Step 3 | Add a new workflow. See Creating a Workflow. | ||
Step 4 | Complete the fields on the Add Workflow Details page. See Defining a Workflow | ||
Step 5 | On the Add User Input page, add a new input. See Defining Workflow Input and Output.
Define an input as follows:
| ||
Step 6 | On the Add User Outputs page, define the workflow's outputs if necessary. See Defining Workflow Input and Output. |
Continue to construct your workflow. See Connecting a Task to a Workflow. The value of the workflow File Upload input that you defined is the path to the file on Cisco UCS Director. The pathname provided on Cisco UCS Director is a directory path ending in your filename combined with a date and time stamp. You can access the file from within any workflow using that path name.
If the zip file contains more than one file, the value of the File Upload input is a semicolon-separated list of the filenames.
To give a workflow access to a file that is selected by a user at runtime, follow these steps:
Step 1 | Choose Orchestration. | ||
Step 2 | On the Orchestration page, click Workflows. | ||
Step 3 | Add a new workflow. See Creating a Workflow. | ||
Step 4 | Complete the fields on the Add Workflow Details page. See Defining a Workflow | ||
Step 5 | On the Add User Input page, add a new input. See Defining Workflow Input and Output.
Define an input as follows:
| ||
Step 6 | On the Add User Outputs page, define the workflow's outputs if necessary. See Defining Workflow Input and Output.
|
Continue to construct your workflow. See Connecting a Task to a Workflow. At runtime, a user must specify a filepath to upload from their workstation. The file is uploaded to Cisco UCS Director and the workflow input becomes the local pathname of the file, assigned in the same manner as if it were an admin input. See Permanently Uploading an Admin-Selected File. The workflow can then access the file until the service request ends. When the service request ends, the file is deleted from Cisco UCS Director.