Chapter 1. New and Changed Information

New and Changed Information

Chapter 2. Overview

Cisco UCS Director Orchestrator

Going Further

Common User Interface Options

Chapter 3. Orchestration Concepts

Introduction to UCS Director Orchestration

Tasks

Workflows

Service Requests

Input and Output

Workflow Validation

Workflow Versioning

Approvals

Rollback

Libraries and Catalogs

Activities

Managing the Workflow Lifecycle

Chapter 4. Creating Workflows

Viewing the Task Library

Creating a Workflow

Defining a Workflow

Defining Workflow Input and Output

Admin Input Filters

Configuring a Task in a Workflow

Connecting a Task to a Workflow

Validating a Workflow

Example: Creating a Workflow

Resolving Workflow Validation Issues

Changing Flow of Control in Workflows

Looping in Workflows

Example: Looping in a Workflow

Adding an If-Then Branch to a Workflow

Using Conditional Branching in a Workflow

Creating Approvals

Chapter 5. Executing Workflows

Workflow Execution

Executing a Workflow

Example: Executing a Workflow

Creating a Workflow Trigger

Example: Creating a Trigger to Execute a Workflow

Scheduling a Service Request

Example: Scheduling Workflow Execution

Using VM Action Policies

Chapter 6. Using Service Requests

Viewing Service Requests

Viewing Service Request Input and Output

Rolling Back a Service Request

Resubmitting a Service Request

Approving and Denying Service Requests

Deleting Service Requests

Chapter 7. Managing Workflows

Workflow Editing

Renaming Workflows

Reordering Inputs

Deleting Workflow Inputs

Renaming Workflow Inputs

Changing Input Optional or Required Status

Editing a Task in an Existing Workflow

Deleting a Workflow

Deleting Multiple Workflows

Exporting and Importing Cisco UCS Director Artifacts

Exporting Workflows, Custom Tasks, Script Modules, and Activities

Importing Workflows, Custom Tasks, Script Modules, and Activities

Workflow Templates

Exporting Workflows as Templates

Importing a Workflow Template

Creating a Workflow from a Template

Predefined Templates

Workflow Version History

Creating a New Version of a Workflow

Choosing the Default Version of a Workflow

Managing Versions of a Compound Task

Cloning a Workflow

Saving a Picture of a Workflow

Chapter 8. Customizing Workflow Components

Creating a Compound Task

Example: Creating a Compound Task

Creating Custom Approvals

Creating Custom Inputs

Macros

Orchestration Macros

Input and Output Macros

Service Request Macros

Virtual Machine Macros

VM Annotations

List of VM Macros and VM Annotations

Chapter 9. Using Activities

Activities

Creating an Activity

Associating an Activity with a Workflow

Adding an Activity to a Workflow

Importing and Exporting Activities

Deleting an Activity

Chapter 10. Using Script Modules

Using Script Modules

Adding Script Modules

Adding Libraries

Accessing Libraries

Jar Files

Adding Jar Files

Lists of Values

Adding a List of Values

Editing a List of Values

Deleting a List of Values

Tabular Reports

Adding a Tabular Report

Editing a Tabular Report

Deleting a Tabular Report

Context Mapping

Enabling Metadata

Adding a Context Mapping

Editing a Context Mapping

Deleting a Context Mapping

Importing and Exporting Script Modules

Preface

Audience

Conventions

Related Documentation

Documentation Feedback

Obtaining Documentation and Submitting a Service Request

Copyright Page

Chapter 1. New and Changed Information

This chapter contains the following sections:

- New and Changed Information

New and Changed Information

The following table provides an overview of the significant changes to this guide for this current release. The table does not provide an exhaustive list of all changes made to this guide or of all new features in this release.

New and Changed Information for Release 5.5

Feature

Description

Where Documented

Rollback can be disabled for a task in a workflow.

When creating or editing a workflow, you can disable rollback of any or all tasks in the workflow.

Configuring a Task in a Workflow.

Cancelled service request can be resubmitted.

You can now submit a service request that was cancelled.

Resubmitting a Service Request.

Define default values for task user inputs.

While editing or creating a workflow, the workflow creator can enable the option for a user to override an administrator input at runtime. The administrator input value is used if the user does not enter a value.

Configuring a Task in a Workflow.

Delete multiple user inputs.

While you are editing or cloning a workflow, more than one user input can be deleted at a time.

Deleting Workflow Inputs.

Delete service requests.

You can delete archived service requests.

Deleting Service Requests.

Chapter 2. Overview

This chapter contains the following sections:

- Cisco UCS Director Orchestrator

- Going Further

- Common User Interface Options

Cisco UCS Director Orchestrator

The Cisco UCS Director Orchestrator (also called the Cisco UCS Director Orchestration Engine, or just Orchestration) enables IT administrators to automate cloud deployment and provisioning and to standardize IT services.

At the scale of cloud computing, manually performing actions such as creating VMs and provisioning networks is prohibitively time-consuming. In Cisco UCS Director, these actions, or tasks, are executable elements that can be run from the GUI. Cisco UCS Director Orchestrator further automates these complex tasks by organizing them into workflows.

Orchestrator works by executing a series of scripted actions called tasks. Each task performs one action. By connecting tasks so that the input of one task is the output of a previous task, you build up a workflow to automate administrative processes such as creating VMs, provisioning baremetal servers, setting up storage, compute, and network resources, and many others.

Going Further

The following documentation describes how to go further with Cisco UCS Director Orchestrator by using advanced scripting capabilities not covered in this basic guide to Orchestration.

- For a description of scripting technologies available in Cisco UCS Director and help choosing the right solution for your application, see the Cisco UCS Director API Customization and Integration Guide.

- For an introduction to developing custom tasks, see the Cisco UCS Director Custom Task Getting Started Guide.

- For examples of scripts that can be used to customize tasks, see the Cisco UCS Director CloupiaScript Cookbook.

For more information about installing, configuring, and administering Cisco UCS Director, see the guides available at the Cisco UCS Director Product Support Home website.

Common User Interface Options

The following table describes the options that are available on all pages of the application user interface. These options perform the same task on every page.

Icon

Label

Description

Refresh

Refreshes the reported data on the page.

Favorite

Adds a page to the Favorites menu.

You can use this option to view frequently accessed pages more quickly.

Add

Brings up the Add dialog box, from which you can add a new resource.

Edit

Brings up the Edit dialog box, from which you can edit a resource.

Customize Table

Brings up the Customize Report Table dialog box, in which you choose what columns you want to include on the screen.

Export Report

Brings up the Export Report dialog box, from which you download a report to your system.

You can generate a report in one of the following formats:

- PDF

- CSV

- XLS

Expand

Expands all the folders that are displayed on the page.

Collapse

Collapses all the folders that are displayed on the page.

Add Advanced Filter

Provides extra filtering parameters on the page.

Search Field

Accepts a keyword to filter for specific records on the page.

Chapter 3. Orchestration Concepts

This chapter contains the following sections:

- Introduction to UCS Director Orchestration

- Tasks

- Workflows

- Service Requests

- Input and Output

- Workflow Validation

- Workflow Versioning

- Approvals

- Rollback

- Libraries and Catalogs

- Activities

- Managing the Workflow Lifecycle

Introduction to UCS Director Orchestration

The concepts described in this chapter are essential to understanding and using Cisco UCS Director Orchestrator. Even if you are familiar with orchestration in general, review this chapter for concepts specific to Cisco UCS Director.

We recommend that you become familiar with the functionality available in Cisco UCS Director before using Cisco UCS Director Orchestrator. If you are unfamiliar with Cisco UCS Director, a thorough introduction is available in the Cisco UCS Director Fundamentals Guide.

Tasks

A task is the atomic unit of work in Cisco UCS Director Orchestrator. A task is a single action or operation with inputs and outputs (except in rare cases where the task operation does not require inputs or outputs). A task cannot be decomposed into smaller operations (exception: a compound task is made up of atomic tasks; see Creating a Compound Task. But for now, think of a task as an indivisible unit of orchestration work).

Cisco UCS Director has a task library containing hundreds of predefined tasks that cover most of the actions an administrator must perform using Orchestration. In cases where there is no suitable predefined task, you can create custom tasks; see the Cisco UCS Director Custom Task Getting Started Guide.

Some examples of predefined tasks are:

- SSH Command task - Execute a command in a secure shell (SSH) session.

- Collect Inventory Task - Gathers information about available devices.

- Create New User - Add a user to the system.

- New VM Provision - Create a new VM (hypervisor-specific).

Workflows

A workflow is a series of tasks arranged to automate a complex operation. The simplest possible workflow contains a single task, but workflows can contain any number of tasks.

Workflows are the heart of the Cisco UCS Director Orchestrator; they enable you to automate processes of any level of complexity on your physical and virtual infrastructure.

You build workflows using the Workflow Designer, a drag-and-drop interface. In the Workflow Designer, you arrange tasks in sequence and define inputs and outputs to those tasks. Outputs from earlier tasks are available to use as inputs to any subsequent task.

Looping and conditional branching can be implemented using special flow-of-control tasks.

Service Requests

Service Requests are closely related to workflows. You create service requests by running workflows; a service request is generated every time you execute a workflow in Cisco UCS Director. A service request is a process under the control of Cisco UCS Director.

You can schedule a workflow for later execution, and Cisco UCS Director stores details of completed service requests. Thus a service request can have one of several states depending on its execution status: it can be scheduled, running, blocked (for example, awaiting an approval; see Approvals), completed, or failed (a service request can fail when one of its component tasks fails to execute properly; see Rollback and Resubmitting a Service Request).

Input and Output

Both tasks and workflows can have any number of input and output variables (inputs and outputs).

Any task or workflow input can be either mandatory or optional. A task or workflow cannot run without all of its mandatory inputs. You define whether an input is mandatory or optional when you create the task or workflow.

Input and Output Types

There are many input types defined in Cisco UCS Director representing a broad selection of categorical, numeric, and text parameters. For example, some existing data types are:

- Generic Text Input (the least restricted input type)

- IPv4 Address

- OS Type

- Memory Size Selector

You choose existing input types from a list that displays a name, type, and category for each variable. The list can be filtered to make finding a given data type manageable.

If none of the existing data types serves your need in a particular application, it is possible to create custom data types by defining restrictions on existing data types.

Connecting Inputs and Outputs

When you construct workflows, you connect an output of one task to the input of another task. For example, consider the following two tasks:

1. A Create User task that produces a user ID as an output.

2. An Add User to Group task that takes a group ID and a user ID as input.

In this instance, you would position Task 1 before Task 2, feeding the user ID output of Task 1 to the user ID input of Task 2.

A workflow's inputs and outputs connect to the inputs and outputs of one or more of its tasks.

User and Administrator Inputs

Administrator inputs (admin inputs) are default values specified at the time a workflow is defined. When defining the workflow the administrator can also allow users to override a default value.

Workflow user inputs are inputs with values specified by a human user at runtime. User inputs can have default values. A user has the option of accepting a default input or overriding it. If the input is mandatory and no default value is specified, the user must input a value.

Instead of dictating a specific input value, an administrator can place restrictions on a user input value when creating a workflow. For example, an admin can restrict the values of an IP address input to a certain range. In this case the IP address is still a user input, but with a restricted range of allowable values.

Some workflows must have admin inputs defined for all of their mandatory inputs. This is the case when workflows are run without human intervention—For example, when a system is configured to run a scheduled workflow at a specific time.

Workflow Validation

Orchestrator provides a mechanism for validating the flow of data from one task to the next in a workflow. Workflow validation checks the data bindings and connections between tasks. Some common issues detected during validation are:

- Missing mandatory values—A required value is not supplied to a task.

- Mapping mismatch—A connected task input/output pair do not have the same data type.

- Missing inputs—This can happen especially after an import or upgrade.

- Task handler not found—An underlying class required to run the task is missing. This message appears if you try to use an unlicensed feature, or if you try to validate a workflow template.

Orchestrator supplies a wizard-based issue resolver. When you validate a workflow, the wizard presents a list of issues along with suggestions for fixing those issues. Some issues require additional information or input from you. Other issues are quick fixes that are resolved for you.

Workflow Versioning

All Orchestrator workflows have a version history. With the version history, you can revert a workflow to an earlier version or create a new version.

The default version of a workflow is the one that appears on the Workflows page. You can set any version in the workflow's history to be the default workflow. When you modify a workflow, you modify only the default version; other versions are unchanged.

Workflows are deleted on a version basis. That is, you can delete one or more versions of a workflow without affecting the remaining versions.

Approvals

An approval is a "gate" task that requires the intervention of a Cisco UCS Director user to allow a workflow to run to completion. This user is typically an administrator who has go-or-no-go authority over the workflow process. See Approving and Denying Service Requests.

You can create custom approvals that allow users to enter input values when they approve a workflow. For example, you can create a custom approval to enable an IT administrator to approve provisioning of a VM, then specify the memory size of the VM before the workflow creates the VM.See Creating Custom Approvals.

Rollback

Workflows can be "rolled back" to a state identical or similar to the state before the workflow was executed. You can do this, for example, to remove virtual components that were created in error.

The term "rollback" often implies that a process is transactional, especially in systems using relational technology. However, it is important know that workflows are not transactional in a relational database sense. Instead, rollbacks work like this:

- Each task consists of two scripts. One script performs the work that the task was designed for. The other is a rollback script designed to "undo" the task. For example, if a task creates a VM, the rollback script deletes the VM.

- When you run a workflow, the scripts of the tasks in that workflow are executed in the order indicated by the workflow.

- When you roll back a workflow, the task rollback scripts are run in the reverse of the order they are run during normal workflow execution.

- A request to roll back a workflow creates a new service request, unconnected to the original service request.

- State information can be saved and used to roll back a task. For example, if you run a task to resize a VM, the pretask size can be saved to enable a rollback. This state persistence is a feature of the API that is used to write tasks; see the Cisco UCS Director Custom Task documentation for details.

- Tasks are atomic; workflows are not. You can roll back a workflow starting with any task in the workflow, but you cannot partially roll back a task.

- It is possible for a workflow to partially succeed; that is, for some but not all of its tasks to execute. Similarly, it is possible for a rollback to completely or partially fail; that is, that some or all of the rollback scripts could fail to execute.

- It is possible for a task to be written with a defective rollback script, or without a rollback script altogether. (Omitting the rollback script is not recommended.)

See Rolling Back a Service Request for instructions on how to roll back a workflow.

Libraries and Catalogs

Libraries and catalogs are collections of predefined tasks and workflows, respectively, from which you can build workflows specific to your needs. For example, you can:

- Copy a predefined workflow that performs a process you require and modify it with parameters particular to your installation.

- Copy a predefined workflow that performs a process similar but not identical to your needs and modify it by adding, modifying, or removing tasks.

- Build a workflow to suit your unique needs entirely from predefined tasks.

Activities

An activity is a placeholder for a type of workflow—A kind of generic front-end that abstracts workflows from their implementation details. You can create an activity for a generic task then associate one or more workflows with the activity to actually perform the required work.

For example, consider a situation in which you need to create two different types of datastore—Say a NetApp datastore and an EMC datastore. You can define one activity called "Create Datastore," then associate both workflows with it. The activity matches input conditions at runtime to determine which storage type is being used, and then run the correct workflow.

In addition, an activity can be used as a workflow task, providing more flexibility to perform context-dependent activities within workflows.

Activities are described in Activities.

Managing the Workflow Lifecycle

Workflow management consists of the organization, storing, updating, creation, and deletion of catalogs of workflows. Cisco UCS Director provides a complete set of actions to enable workflow management.

Operations used to manage workflows are described in the following table, with references to their respective task descriptions in this guide.

Operation

Description

Add a Workflow

Create a workflow from scratch. Use the Add action in the Workflows tab. See Creating a Workflow.

Add a Workflow to a Catalog

Create a catalog of workflows for subscribers, for example application administrators. See the Cisco UCS Director Administration Guide for information about publishing and managing catalogs.

Add and Arrange Tasks in a Workflow

Use the Workflow Designer action in the Workflows tab to open the Workflow Designer. See Configuring a Task in a Workflow and Connecting a Task to a Workflow.

Choose a Workflow Version

Choose the active version of a workflow. The active version is called the default version and appears on the Workflows page. Use the Manage Versions action in the Workflows tab. See Choosing the Default Version of a Workflow.

Clone a Workflow

Create a renamed copy of a workflow. The copy has a new version history. Use the Clone action in the Workflows tab.

Create a New Version of a Workflow

Use the Create New Version action in the Workflows tab. See Creating a New Version of a Workflow.

Delete a Workflow

Remove one or more or all versions of a workflow from Cisco UCS Director. Use the Delete action in the Workflows tab.

Edit a Workflow

Modify the name, location, inputs, and outputs of a workflow (but not the tasks). Use the Edit action in the Workflows tab. See Workflow Editing.

Execute a Workflow

Create a service request immediately from the selected workflow. Use the Execute Now action in the Workflows tab. See Executing a Workflow.

Export a Workflow

Save a workflow in a format that can be loaded in another Cisco UCS Director appliance. Use the Export action in the Workflows tab. See Exporting Workflows, Custom Tasks, Script Modules, and Activities.

Export a Workflow as a Template

Export the selected workflow as a template in XML-based format. Use the Export Template action in the Workflows tab. See Exporting Workflows as Templates.

Import a Workflow

Load a workflow created elsewhere into Cisco UCS Director. Use the Import action in the Workflows tab. See Importing Workflows, Custom Tasks, Script Modules, and Activities

Lock or Unlock a Workflow

Lock a workflow to prevent any modifications. Use the Lock/Unlock action in the Workflows tab to lock and unlock selected versions of a workflow. Once locked, the workflow cannot be deleted or edited.

Move a Workflow

Move a workflow to a new directory. Use the Edit action in the Workflows tab and select a different folder on the Edit Workflow Details page. See Workflow Editing.

Validate a Workflow

Analyze the workflow to determine that the task inputs and outputs are properly connected. Use the Validate button in the Workflow Designer window. See Validating a Workflow.

View an Entire Workflow

View the entire structure of a workflow, in which you can pan a magnified section to view details. Use the Full View button in the Workflow Designer window. See Saving a Picture of a Workflow.

Chapter 4. Creating Workflows

This chapter contains the following sections:

- Viewing the Task Library

- Creating a Workflow

- Example: Creating a Workflow

- Resolving Workflow Validation Issues

- Changing Flow of Control in Workflows

Viewing the Task Library

Cisco UCS Director contains web-based documentation on all predefined tasks. To view the documentation, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Task Library action.

Step 3

Check the Regenerate document check box to include new tasks and tasks created using Cisco UCS DirectorOpen Automation.

Step 4

Click Submit. The Orchestration Task Library appears in your default web browser.
Note:
There are several hundred entries. You can use your browser's search function to find a particular task.

Step 5

Click an entry to see detailed information about a task.

Creating a Workflow

Creating a workflow can be broken down into five overall steps:

1. Define the workflow. To define a workflow, you name the workflow and select a few other details.

2. Define the workflow inputs and outputs. You specify which input parameters the workflow requires to execute, and what output results from its execution.

3. Once the workflow inputs and outputs are defined, use the Workflow Designer to add a workflow task to the workflow.

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

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

- Defining a Workflow

- Defining Workflow Input and Output

- Admin Input Filters

- Configuring a Task in a Workflow

- Connecting a Task to a Workflow

- Validating a Workflow

Defining a Workflow

To define a workflow, do the following:

Step 1

Navigate to Policies > Orchestration.

Step 2

Click the Workflows tab.

Step 3

Click the Add action.

Step 4

In the Add Workflow Details screen, complete the following fields:

Name

Description

Workflow Name field

The workflow name.
Note:
Workflow names cannot contain the following characters: \"%&'*+,./:;<=>?^|

Version label (not editable)

Displays which version of the workflow you are creating or editing.

Description field

A description of the workflow. (Optional.)

Workflow Context drop-down list

The workflow context. Cisco UCS Director Orchestrator supports the following options:

- Any—Enables you to use the workflow in any context.

- Selected VM—Enables you to execute the workflow only when you choose a VM.

Save as Compound Task check box

Define the workflow as a compound task. See Creating a Compound Task.

Publish Task outputs as Compound Task outputscheck box

This check box appears if you choose the Save as Compound Task check box.

Check this check box to expose all the task outputs as outputs of the compound task. Leaving the box unchecked suppresses the outputs of the included tasks so that the compound task exposes only the workflow outputs.

Always execute during System initialization check box

Check this check box to execute the workflow as part of the startup sequence when Cisco UCS Director is initialized.

Note:
Because the workflow is executed before the Cisco UCS Director GUI starts, workflows that require user input cannot be executed at system startup.

Place in New Folder check box

Create a new folder in which to place the workflow. If you check this check box, the Select Folder drop-down list becomes a text field. Type the name of the new folder.

Select Folder drop-down list

The folder in which to place the workflow.

Notify status of execution to initiating user check box

Email the result status to the user who invoked the workflow. If checked, you can notify more users by entering their email addresses in the Additional User(s) to send Email Notification field.

The result status for the workflow can be one of the following:

- Completed status

- Failed execution status

- Cancelled execution status

Leave the check box unchecked to use an email policy.

Email policy drop-down list

Instead of specifying email recipients individually, you can use an orchestration notification email policy. Default policies exist to notify:

- The user that starts execution of the workflow

- The user and the user's group

- The user's group and that group's administrator

You can define your own policies as well by navigating to Administration > System > Orchestration Policy and selecting Add. Policies you create are available in the Email policy drop-down list.

What to Do Next

Click Next to define input and output for the workflow.

Defining Workflow Input and Output

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.

Before You Begin

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.

- To associate the workflow with an activity:

1. Check the Associate to Activity check box.

2. In the Activity drop-down list, choose the activity with which to associate the workflow. The activity's inputs populate the input list.

3. Skip the rest of this step.

- To define inputs for the workflow without an activity, continue with this step:

1. In the Workflow User Inputs screen, click the + icon at the top of the list of values.

2. In the Add Entry To dialog box, complete the following fields:

Name

Description

Input Label field

The name or label of the input parameter.

Input Description field

A description of the input parameter.

Optional check box

Make the input parameter optional (not mandatory) at the time of workflow execution.

Input Type button

Click this button to choose the data type of the input parameter.

Note:
Reduce the number of input types by typing a match string in the filter field at the top of the list.

Note:
If you later edit a workflow, the Input Type field is not editable.

Multiline/Multiple Value Input check box

The effect of this option depends on the input type.

This option is available only for the Generic Text input type. Check the box to allow the user or administrator to enter multiple lines for the input value.

Note:
You cannot map a multiline workflow input to a single-line task input. When creating or editing a task, no multiline workflow inputs appear in the User Input drop-down list on the User Input Mapping page.

Input Field Size drop-down list

This list appears if you choose the Multiline Input check box. Choose a size for the text area that is displayed to enter the input value.

Value Restrictions heading

Depending on the input type that you have chosen, one or more of the following are available:

- Admin Inputcheck box—Check this box to populate inputs with default values. User input is then optional at run time.

- Admin Input Filter—Check this box to define a rule-based filter to restrict available input values. User input is required at run time from the restricted range of values. See Admin Input Filters.

- Admin Input List—Check this box to define an item-by-item list of available input values. User input is required at run time from the admin-selected list of values.

Admin Input field

Available when you check the Admin Input check box. Click Select to choose one or more admin input values.

Override Admin Input Value check box

Available when you check the Admin Input check box. Check this box to enable the user to replace the administrator value at runtime. Leaving this box unchecked hides the user's input control for this value at runtime.

Input Filter Criteria text field

Available when you click the Admin Input Filter check box. Type a filter expression to limit the values available at run time. See Admin Input Filters.

Admin Input Value list

Available when you click the Admin Input Filter check box. Displayed for reference—Use the column headings as attribute names in your filter expression.

Select button and list

Available when you click the Admin Input List check box. Click Select, then choose a value or values. All chosen values are available as user input choices at run time.

3. If necessary, add more inputs by repeating the previous two substeps.

Step 2

Click Next.

Step 3

To enter outputs for the workflow, do the following.

1. In the Workflow User Outputs screen, click the + icon at the top of the list of values.

2. In the Add Entry To dialog box, complete the following fields:

Name

Description

Output Label field

The name or label of the output parameter.

Output Description field

A description of the output parameter.

Optional check box

Make the output parameter optional (not mandatory) at the time of workflow execution.

Type field

The data type of the output parameter. During the editing and saving of a workflow task, the Type field is no longer editable.

3. If needed, add more outputs by repeating the previous two substeps.

Step 4

Click Submit. The new workflow opens in the Workflow Designer.

What to Do Next

Add tasks to the workflow using the Workflow Designer. See Configuring a Task in a Workflow.

Admin Input Filters

Filtering Tabular Data

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:

- EQUALS

- NOT_EQUALS

- CONTAINS

- NOT_CONTAINS

- IS_SUBSET

- NOT_SUBSET

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.

Filtering Lists of Values

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

Filtering Numeric Data

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.

Configuring a Task in a Workflow

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:

Before You Begin

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:

Name

Description

Task Name field

A name for this instance of the task. You can accept the automatically generated default or enter your own name for the task.

Task Category drop-down list

The category (also the folder name) in which the task appears. Cannot be changed.

Task Type drop-down list

The type (or generic name) of the task. Cannot be changed.

Comment field

An optional comment about this use of the task in this workflow.

Retry Execution check box

Check this box to retry the task if it fails. The Retry Count and Retry Frequency controls appear.

Disable Rollback check box

Check this box to disable the task's rollback script. If you check this box, the task is unchecked in the Rollback Service Request dialog and cannot be rolled back; see Rolling Back a Service Request.

If the task does not support rollback, checking this box has no effect.

Retry Count drop-down list

The number of times (up to 5) to retry the task on failure.

Retry Frequency field

A comma-separated list of integers specifying how many seconds to wait between retries. For example, if you selected a retry count of three, enter 1, 10, 60 to retry after one, 10, or 60 seconds, respectively.

Step 6

Click Next.

Step 7

In the User Input Mapping screen, complete the following fields:

Name

Description

Manage Workflow User Inputs button

Click this button to add to or edit the workflow user inputs.

Task Input headings

Each task input is displayed as a heading on the remainder of this page. The input is labeled (Mandatory) if it required.

Map to User Input check box

Below each task input heading is a check box. Check this box to populate the task input from a workflow user input at runtime.

User Input drop-down list

This drop-down list appears if you check the Map to User Input check box. Select the workflow user input to map to the task input.

Note:
You cannot map a multiline workflow input to a single-line task input. The multiline workflow input does not appear in the User Input drop-down when creating or editing a task. See Defining Workflow Input and Output.

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:

Name

Description

Task Input heading

Each task input that was not mapped to a user input on the previous page is displayed with an appropriate input control (text field, drop-down list, and so on). Use the input controls to specify the value. Optional inputs can be left blank.

Step 10

Click Next.

Step 11

In the User Output Mapping screen, complete the following fields:

Name

Description

Task Output heading

Each task output is displayed as a heading on this page. The output is labeled (Mandatory) if it required.

Map to User Output check box

Below each task output heading is a check box. Check this box to populate a workflow user output from the task output at runtime.

User Output drop-down list

This drop-down list appears if you check the Map to User Output check box. Select the workflow user output to map to the task output.

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.

What to Do Next

Connect the task to the workflow.

Connecting a Task to a 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.

Before You Begin

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:

1. Mouse over the bottom of the task from which you want to map an output. The On success or On failure drop-down appears, depending on which side of the box your cursor occupies.
Note:
The Start task has only one (unlabeled) drop-down.

2. Click and hold your left mouse button.

3. Drag the cursor anywhere inside the task to which you are connecting, and release the mouse button. A colored arrow connects the two tasks, indicating the flow of operation from one task to the other.

Note:
Instead of dragging and dropping, you can click the down-arrow icon and choose the name of the task to which you want to connect. The colored arrow appears as if you had dragged it to that task.

Note:
Typically you connect a task's On success drop-down to the next task, and connect the On failure drop-down to the Completed (Failed) task. There are exceptions, however. For example, you could insert a task to do cleanup or error handling, in which case you would connect On failure to the cleanup task.

However, the Workflow Designer does not permit you to connect a task's On success drop-down to the Completed (Failure) task.

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.

What to Do Next

Add more tasks if necessary to complete the workflow. When you are finished, validate the workflow.

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.

Before You Begin

A workflow is open in the Workflow Designer.

Click the Validate button. Task connection errors are displayed in red above the affected tasks. If no errors are detected, a success dialog pops up.

What to Do Next

If connection errors are displayed in the Workflow Designer, use the Workflow Validation tool to resolve the issues. See Resolving Workflow Validation Issues.

Example: Creating a Workflow

This simple example walks you through the creation of a workflow that power cycles (turns off and back on) a VM.

Before You Begin

You must have a VM available in Cisco UCS Director.

Step 1

Define the workflow. Do the following:

1. Navigate to Policies > Orchestration.

2. Click the Workflows tab.

3. Click the Add action.

4. Complete the fields in the Add Workflow Details screen as follows:

Field

Entry

Workflow Name field

Type PowerCycleVM.

Description field

Type Shut down and restart a VM.

Workflow Context drop-down list

Select Any.

Save as Compound Task check box

Leave this unchecked.

Always execute during System initialization check box

Leave this unchecked.

Place in New Folder check box

Check this check box.

Folder Nametext field

Type OrchestrationExamples

Notify status of execution to initiating user check box

Leave this unchecked.

Email policy drop-down list

Choose No email.

Version Label text field

Leave the default value, 0.

5. Click Next.

Step 2

Define an input to specify the name of the VM. Do the following:

1. In the Workflow User Inputs screen, click the + icon at the top of the list of values.

2. Complete the fields in the Add Entry To dialog box as follows:

Field

Entry

Input Label field

Type VM Name.

Input Description field

Type Name of the VM to power cycle.

Optional check box

Leave this unchecked.

Input Type button

Click the button labeled Select .... The Select dialog comes up.

3. In the Select dialog, type vm selector in the search box.

4. Click the check box next to the VM Selector entry.

5. Click Select.

6. Define an administrator (fixed) value for the VM name by completing the next set of fields as follows:

Field

Entry

Admin Input check box

Check this check box.

Admin Input Filter and Admin Input List check boxes

These check boxes disappear when you check Admin Input. Both of these check boxes enable the administrator to filter the choices available to the user when the workflow is run. Instead, for this example, the Admin Input Value supplies a single fixed value at runtime.

h

Override Admin Input Value check box

Leaving this box unchecked hides the user's input control for this value at runtime. For this example, leave the box unchecked.

Admin Input Value button

Click Select to choose a value for the administrator input. The Select list of values comes up.

Click a check box to select an existing VM instance, then click Select.

7. Click Next.

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:

1. In the Available Tasks search field at the top left of the Workflow Designer window, type power. The Available Tasks window now displays only tasks containing the string power.

2. From the Generic VM Tasks folder, drag and drop the VM Power Action icon into the work area. The Add Task dialog appears.

3. In the Task Information dialog, type Power Off 1 in the Task Name text field.

4. Click Next.

5. In the User Input Mapping dialog, complete these fields:

Field

Entry

Map to User Input check box

Check this check box.

User Input drop-down list

Since there is only one user input of the correct type (or of any type, in this case), the user input name that you created (VM Name) is already selected in the drop-down list.

6. Click Next.

7. In the Task Inputs dialog's VM Action drop-down list, select Power OFF.

8. Click Next.

9. Click Submit. The task is automatically connected in the new workflow.

Step 5

Add a task to power on the VM. The procedure is similar to the previous step, with the following differences:

- In the Task Information dialog, type Power On 1 in the Task Name text field.

- In the Task Inputs dialog's VM Action drop-down list, select Power ON.

Note:
You could create this workflow with a single Reboot task rather than powering off and back on. However, for purposes of this example go ahead and create the workflow with the two power management tasks.

- When you click Submit, the task does not automatically connect to the existing workflow. Instead, connect it by hand:

1. Mouse over the lower left corner of the Power Off 1 task icon. The On Success drop-down appears.

2. Drag and drop from the On Success drop-down area to anywhere in the Power On 1 icon.

The Power On 1 task is inserted between the Power Off 1 task and the Completed task.

3. Using the same drag-and-drop technique, connect the Power On 1 > On Failure drop-down to the Completed (Failed) task.

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.

Resolving Workflow Validation Issues

Cisco UCS Director supplies a wizard-based tool to aid you in troubleshooting workflow validation errors.

Before You Begin

A workflow has failed validation in the Workflow Designer.

Step 1

On the menu bar, choose Policies > Orchestration.

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.

Changing Flow of Control in Workflows

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:

- Loops.

- If-then branches.

- Conditional switches with an arbitrary number of branches.

- Looping in Workflows

- Example: Looping in a Workflow

- Adding an If-Then Branch to a Workflow

- Using Conditional Branching in a Workflow

- Creating Approvals

Looping in Workflows

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:

- By count—Iterate a specified number of times.

- By item—Iterate over a list of items.

Before You Begin

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:

Name

Description

Task Name field

The name of the task.

Comment field

Comments for the task.

Retry Execution check box

Check the check box to retry later if the task fails.

Retry count drop-down list

Choose the number of retry attempts.

Retry Frequency drop-down list

Choose the duration between retry attempts.

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:

Name

Description

List based iteration check box

Check this check box to perform the loop tasks on every item in a list. The following two fields appear.

Input for list-based iteration

Choose a list of input values for the list-based iteration.

User Input to assign iterated values drop-down list

The user input for the list-based iteration.

Create a workflow input with the same type as your list elements and map it to the Start Loop task here.

Count based iteration check box

Check this check box to perform loop tasks based on a count. The following field appears.

Number of times to loop field

The number of times to perform the loop.

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.

Example: Looping in a Workflow

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.

Before You Begin

Create the example workflow as described in Example: Creating a Workflow.

Step 1

Open the PowerCycleVM workflow.

1. Navigate to Policies > Orchestration.

2. Click on the Workflows tab.

3. Locate and select the PowerCycleVM workflow you created in Example: Creating a Workflow.

4. Click on Workflow Designer.

Step 2

Add the Start Loop task to the workflow.

1. From the Available Tasks window in the Procedural Tasks folder, drag and drop Start Loop onto the work area.

2. In the Task Information window, complete the following fields:

Field

Entry

Task Name text field

Type StartVMLoop.

Comment text field

Type Loop through a list of VMs

Task Details heading

Make a note of the message under the Task Details heading regarding the task output START_LOOP_OUTPUT.

3. Click Next.

4. Replace the workflow input to accept a list of VMs
. In the User Input Mapping window, click Manage Workflow User Inputs.

5. Click the Add icon.

6. In the Add Entry To dialog, complete the following fields:

Field

Entry

Input Label text field

Type VM Names.

Input Description text field

Type List of VMs to restart..

Optional checkbox

Leave this unchecked.

Input Typebutton

Click this button to bring up the Select list of values.

Use the search box to locate and select multiVM as the input type.

Click Select.

Value Restrictions heading

Click the Admin Input checkbox.

Click Select.

Choose several VMs , then click Select.

7. Click Submit.

8. On the User Input Mapping window, under the Input for list based iteration heading, check the Map to User Input checkbox. The User Input drop-down list appears.

9. In the User Input drop-down list, select VM Names.

10. Click Next.

11. Check the List based iteration checkbox. The User input to assign iterated values drop-down list appears.
Note:
This field is a feature of the Start Loop task. Since the output variable START_LOOP_OUTPUT is of type generic text, it cannot (usually) be mapped to the input of the tasks inside the loop. Instead, the Start Loop task assigns each item of the input list to the variable as it iterates.

12. Select VM Name in the User input to assign iterated values drop-down list.
Note:
There is nothing special about the VM Name workflow input variable; you are reusing it since you no longer need it as input to the workflow. (The workflow input is now VM Names, which is a list of VMs.)

13. Click Next.

14. There is no output mapping, so click Submit to save the task.

15. Drag and drop to connect the Start task to the StartVMLoop task. The Workflow Designer connects the StartVMLoop > On Success dropdown to the Power Off 1 task (because it was the previous target of the Start task).

16. Drag and drop to connect the StartVMLoop > On failure dropdown to the Completed (Failed) task.

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:

1. Drag and drop the End Loop task from the Procedural Task folder onto the work area.

2. In the Task Information window, complete the following fields:

Field

Entry

Task Name text field

Type EndVMLoop.

Comment text field

Type End of VM loop.

3. Click Next.

4. In the User Input Mapping window, click Next.

5. In the Task Inputs window, click Next.

6. In the User Output Mapping window, click Next.

7. Drag and drop to connect the Power On 1 task to the EndVMLoop task.

8. Drag and drop to connect the EndVMLoop > On failure dropdown to the Completed (Failed) task.

Step 4

Click Close to close the Workflow Designer.

What to Do Next

Execute the task to restart the VMs specified in the workflow.

Adding an If-Then Branch to a Workflow

You can create a two-way branch in a workflow using an if-then construct.

Before You Begin

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:

Name

Description

Task Name field

The name of the task.

Comment field

Comments for the task.

Retry Execution check box

Check the check box to retry later if the task fails.

Retry count drop-down list

Choose the number of retry attempts.

Retry Frequency drop-down list

Choose the duration between retry attempts.

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:

Name

Description

Specify the condition field

Enter the condition evaluated to determine the course of the workflow. The flow of control depends on whether the condition evaluates to true or to false.

The conditions that you define must contain only the following operators:

==, !=, <, <=, >, >=, ||, &&, contains, startsWith, endsWith

Following are some example conditions:

- TaskName.OUTPUT_ATTRIBUTE_NAME == "2"

- WORKFLOW_USERINPUT_LABEL_NAME contains "xyz"

- TaskName.OUTPUT_ATTRIBUTE NAME == WORKFLOW_USERINPUT_LABEL_NAME || WORKFLOW_USERINPUT_LABEL_NAME != "123"

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).
Note:
Do not confuse the False and On Failure connectors. The False connector defines the path if the condition statement evaluates to false. The On Failure connector defines the path for failure of the task, for example if the task cannot evaluate the condition statement.

Using Conditional Branching in a Workflow

You can create a multiple-path branch in a workflow using a conditional construct. A single conditional task can have any number of branches.

Before You Begin

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:

Name

Description

Task Name field

The name of the task.

Comment field

Comments for the task.

Retry Execution check box

Check the check box to retry later if the task fails.

Retry count drop-down list

Choose the number of retry attempts.

Retry Frequency drop-down list

Choose the duration between retry attempts.

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.

Note:   The condition statements do not have to be mutually exclusive. At run time, the statements are evaluated in the order they are listed. Execution continues with the path of the first statement to evaluate to true.

Step 7

In the Add Entry to screen, complete the following fields:

Name

Description

Label field

The label for the condition

Condition field

Enter the condition to be evaluated to determine the course of the workflow. The conditions that you define must contain the following operators:

==, !=, <, <=, >, >=, ||, &&, contains, startsWith, endsWith

Following are some examples that you can use while specifying conditions:

- TaskName.OUTPUT ATTRIBUTE NAME=="2"

- WORKFLOW USERINPUT LABEL NAME contains "xyz"

- TaskName.OUTPUT ATTRIBUTE NAME == WORKFLOW USERINPUT LABEL NAME || WORKFLOW USERINPUT LABEL NAME != "123"

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.

Creating Approvals

To require approval of a user, you add an approval task to the workflow.

Before You Begin

Open a workflow in the Workflow Designer.

Step 1

In the Workflow Designer Available Tasks window, open Cloupia Tasks > General Tasks.

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:

Name

Description

Task Name field

The task name.

Comment text box

A comment about the approval task (Optional.)

Retry Execution check box

Leave this box unchecked. If the administrator rejects the approval, the workflow stops with the approval task in a failed state. If you enable execution retries, the workflow presents the administrator with an approval multiple times. This is probably not the behavior you want from the workflow.

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

Name

Description

User ID Select button

Click Select and use the Select dialog to choose the user whose approval is required to execute this workflow. Then click Submit.

Approval required from all the users check box

You can ignore this check box.

Number of approval request Reminder fields

Type the number of times to remind the user to approve this workflow. Entering 0 causes the reminder to be sent until the workflow approval has been approved or rejected.

Reminder Interval (Hours) field

Type the number of hours between approval reminders.

Step 8

Click Next.

Step 9

In the User Output Mapping window, click Submit.

Chapter 5. Executing Workflows

This chapter contains the following sections:

- Workflow Execution

- Executing a Workflow

- Example: Executing a Workflow

- Creating a Workflow Trigger

- Example: Creating a Trigger to Execute a Workflow

- Scheduling a Service Request

- Example: Scheduling Workflow Execution

- Using VM Action Policies

Workflow Execution

When you execute a workflow, a service request is created. You can execute a workflow directly, schedule a workflow to run later, or create a trigger to run a workflow when certain conditions are met. You can also create a policy to execute workflows on VMs.

Each of these options is briefly outlined here.

- Execute a Workflow Directly - You can execute a selected workflow immediately. Navigate to the Policies > Orchestration > Workflows tab or open the Workflow Designer, then choose Execute Now.

- Schedule a Service Request to be Executed Later - You can schedule execution of a selected workflow. Navigate to the Policies > Orchestration > Workflows tab, choose Schedule.

- Trigger Conditional Workflow Execution - You can create a trigger to execute a workflow when a set of conditions is met. Navigate to the Policies > Orchestration > Workflows tab, then choose Triggers.

- Create an Action Policy - You can create a policy to execute workflows on VMs within a virtual data center (vDC). Navigate to the Policies > Orchestration > Workflows tab, choose User VM Action Policy, then add the policy to a vDC.

Detailed instructions and examples are given in the following sections.

Executing a Workflow

You can execute a workflow immediately from either the Workflows page or the Workflow Designer.

Step 1

Navigate to the Workflows page. From the menu, choose Policies > Orchestration, then choose the Workflows tab.

Step 2

Select the workflow you want to execute by navigating to it on the Workflows page (it might be in a directory or subdirectory).
Optionally, open the workflow in the Workflow Designer by clicking the Workflow Designer action.

Step 3

Click the Execute Workflow action.

- If you are in the Workflow Designer, the button is near the upper right of the window.

- If you are on the Workflows page, select the action from the task bar or from the drop-down menu at the right of the task bar.

Step 4

In the Executing Workflow dialog, choose the version of the workflow you want to run.

Step 5

Also in the Executing Workflow dialog, set user inputs for the workflow.
The input controls show the workflow inputs that you are allowed to change as a user.

If an input is mandatory and has no default input, you must provide a user input.

Note:
Workflow inputs can be defined with values (admin inputs) that cannot be overridden at runtime. Admin inputs are not displayed in the Executing Workflow dialog.

Step 6

Click Submit. The Service Request Submit Status dialog appears.

What to Do Next

In the view Service Request Submit Status window, click Show Detail Status to see the progress of the service request.

Example: Executing a Workflow

This example demonstrates executing a workflow directly.

Before You Begin

Create the example workflow as described in Example: Creating a Workflow.

Step 1

Navigate to Policies > Orchestration.

Step 2

Click the Workflows tab.

Step 3

Locate and select the PowerCycleVM workflow you created in Example: Creating a Workflow.

Step 4

In the Executing Workflow dialog, click Submit.

Step 5

In the view Service Request Submit Status window, click Show Detail Status.

Step 6

In the Service Request dialog, click the Workflow Status tab. On the status page is a graphic of the service request's progress.

Step 7

Click the Log tab to view the service request log.
Note:
Click the Refresh button to view the latest updates to the log.

What to Do Next

Click the Workflow Status tab and record the Request ID from the report. You can view the status of a service request by ID at any time; see Viewing Service Requests.

Click Close to leave the Service Request dialog.

Creating a Workflow Trigger

You can define a trigger to execute a workflow when specific conditions are met. These conditions are typically the states of various system components. When you enable a trigger, UCS Director monitors the system state and when the trigger conditions are met executes the workflow you specify.

To create a workflow trigger, follow these steps:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Triggers tab.

Step 3

Click Add.

Step 4

In the Add Trigger: Trigger Information screen, complete the following fields:

Name

Description

Trigger Name field

The name of trigger.

Is Enabled check box

Enables the trigger. (You can create and save a trigger, then enable it later.)

Description field

A description of the trigger.

Frequency drop-down list

The period between checks for the trigger rule. The choices for this period span three minutes to one month.

Trigger Type drop-down list

Choose the trigger type:

- Stateful—The last trigger state is recorded and actions are executed when there is a change in the trigger state. (The trigger state is Active when the trigger conditions are met, and Clear otherwise.) You choose workflows for both trigger state transitions: one for when the trigger state changes from Active to Clear, and one for when the trigger state changes from Clear to Active. The trigger state is checked at the frequency specified in the Frequency drop-down list.

- Stateless—The trigger is executed anytime the trigger conditions are met, at a frequency specified in the Frequency drop-down list.

Step 5

Click Next.

Step 6

Specify the trigger conditions.

1. In the Add Trigger: Specify Conditions screen, do the following: Click (+) to create a condition in the conditions list.

2. In the Add Entry to Monitor dialog box, complete the following fields:

Name

Description

Type of Object to Monitor drop-down list

What type of object to monitor with this condition.

Object drop-down list

Choose the particular object to monitor. Entries in this list vary depending on the type of object. You might need to specify additional information (a pod, for example) to filter for the object.

Parameter drop-down list

Choose an operational parameter to monitor. Entries in this list vary depending on the object.

Operation drop-down list

Choose the relational operation for the trigger comparison. Entries in this list vary depending on the possible states of the parameter.

Value drop-down list

Choose the value with which to compare the parameter. When the relation defined by Parameter, Operation, and Value is true, the trigger state is Active; otherwise, the trigger state is Clear.

3. Click Submit.

4. Repeat the previous two steps to add more trigger conditions.

5. Choose one of the two options in the Trigger When drop-down list:

- Choose All Condition(s) Satisfied to specify that the trigger state is true only when all of the trigger conditions are met.

- Choose Any Condition(s) Satisfied to specify that the trigger state is true if one or more of the trigger conditions are met.

Step 7

Click Next.

Step 8

In the Add Trigger: Specify Workflow screen, choose the workflow or workflows to execute on the trigger:

1. In the Select Workflow drop-down list under When Trigger State Becomes Active, choose a workflow. This workflow is executed:

- Whenever the trigger state is Active (polled at a frequency specified in the Frequency drop-down list), if the trigger is stateless.

- If and only if the trigger state has changed from Clear to Active since last checked one period ago (as specified in the Frequency drop-down list), if the trigger is stateful.

2. If you chose the stateful trigger type, in the Select Workflow drop-down list under When Trigger State Becomes Clear, choose a workflow. This workflow is executed if and only if the trigger state has changed from Active to Clear since last checked one period ago (as specified in the Frequency drop-down list).

Step 9

Click Next.

Step 10

In the Add Trigger: Specify Workflow Inputs screen, enter all the required inputs for the workflow, and any needed optional inputs.
Note:
You must enter all inputs that are needed by the workflow. There is no opportunity for user input in a triggered workflow.

Step 11

Click Submit.

What to Do Next

You can enable or disable a trigger by selecting the trigger in the Policies > Orchestration > Triggers tab and checking or unchecking the Is Enabled check box.

Example: Creating a Trigger to Execute a Workflow

This example demonstrates creating a trigger to execute a workflow when a set of conditions are met.

Step 1

Create a workflow with a single task as follows:

1. Create the workflow as described in the following table.

Name

Description

Workflow Name text field

Type VM Power Event Notify.

Description text box

Type Sends an email when a VM changes power state.

Workflow Context drop-down list

Choose Any.

Select Folder drop-down list

Choose Orchestration Examples.

2. Create an input as described in the following table:

Name

Description

Input Label text field

Type Admin Emails.

Input Description text box

Type Email addresses to send power event notifications.

Optional check box

Leave unchecked.

Input Type drop-down list

Choose email_address_list.

Value Restrictions selections

Do not select the Admin Input check box.

3. Do not define any user outputs.

4. In the Workflow Designer, add a Send Email task to the workflow.

5. Complete the task information as described in the following table:

Name

Description

Task Information page

Task Name text field

Type VMPowerEventEmail.

User Input Mapping page

Email Addresses (Mandatory) heading

Click the Map to User Input check box.

Task Inputs page

Subject text field

This is the subject line of the notification email. Type VM power event notification.

Body text box.

This is the body of the notification email. Type One of the following VMs has had a power -on or power-off event: (list the VMs in your VMPowerCycle workflow).

Value Restrictions selections

Do not select the Admin Input check box.

6. On the User Output Mapping page, do not map any outputs.

7. Validate the workflow, then exit the Workflow Designer.

Step 2

Click the Triggers tab.

Step 3

Click the Add action.

Step 4

On the Trigger Information page, complete the following fields:

Name

Description

Trigger Name text field

Type VMPowerEvent.

Is Enabled check box

Leave this box checked.

Description text box

Type Executes VMPowerEventEmail when a power-on or power-off occurs on a monitored VM.

Frequency drop-down list

To test the trigger, you want a short time between polls. Choose 3 minutes.

Trigger Type drop-down list

Choose Stateful. This causes the trigger to activate when a condition changes between polls.

Step 5

On the Specify Conditions page, add some conditions.

1. Click the + icon to add a condition as specified in the following table:

Name

Description

Type of Object to Monitordrop-down list

Choose VM.

Object drop-down list

Select a VM to be monitored.

Parameter drop-down list

Choose Power Status.

Operation drop-down list

Choose Equals.

Value drop-down list

Choose ON.

2. Repeat the last step to add more VMs to be monitored. Each VM has its own condition.

3. In the Trigger When drop-down list, select Any Condition(s) Satisfied.

Step 6

On the Specify Workflow page, complete the fields as specified in the following table:

Name

Description

Maximum Invocations drop-down list

For demo purposes, choose 20. You might choose Unlimited in an actual production application.

When Trigger State Becomes Active heading

In the Select Workflow drop-down list, choose VMPowerEventNotify. The trigger executes this workflow when any of your monitored VMs changes from OFF to ON as defined on the Specify Conditions page.

Note:
Items appear by serially assigned ID number in the drop-down list, so your workflow is at the bottom of list.

When Trigger State Becomes Clear heading

In the Select Workflow drop-down list, choose VMPowerEventNotify. The trigger executes this workflow when any of your monitored VMs changes from ON to OFF as defined on the Specify Conditions page.

What to Do Next

Test the trigger by turning on or off one of the monitored VMs. Make sure that the VM's state remains changed for at least three minutes. The trigger polls the state, so any change that is not visible at the time of polling (on and back off during the three minute wait interval, for example) does not activate the trigger.

Scheduling a Service Request

You can schedule execution of a workflow for a specific time.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

In the Workflows pane, choose the workflow that you want to schedule.

Step 4

Click Schedule.

Step 5

In the Schedule Workflow screen, complete the following fields:

Name

Description

Recurrence Type drop-down list

Whether and at what frequency you want the workflow execution to recur. Choose one of the following:

- No End—Execute the workflow repeatedly without end at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

- Only once—Execute the workflow only once, at Start Time.

- Fixed Number of Times—Execute the workflow a number of times specified by Repeat Count at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

- End by Date—Execute the workflow until the defined end time at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

Start Time field

The time at which to start the workflow execution (or the first of a series of recurring executions).

Frequency Type drop-down list

The unit of the recurrence frequency interval. Choose hourly, daily, weekly, or monthly.

Frequency Interval drop-down list

Choose the interval at which the workflow needs to be executed for the frequency that you chose. For example, if the Frequency Interval is four and the Frequency Type is daily, the workflow is executed every four days.

User ID field (optional)

The user ID to run the workflow.

Note:   You must provide inputs with the workflow. Scheduled workflows do not accept user input.

What to Do Next

Choose the Workflow Schedules tab to view scheduled workflows.

In the Workflow Schedules pane, you can modify a scheduled workflow by choosing a workflow and clicking the Edit button. The Modify Workflow Schedule dialog box appears. Modify the fields described in the previous steps. The Modify Workflow Schedule dialog box is identical to the Schedule Workflow dialog box.

Example: Scheduling Workflow Execution

This example demonstrates how to schedule a workflow for later execution.

Before You Begin

Create the example workflow as described in Example: Creating a Workflow.

Step 1

Navigate to Policies > Orchestration.

Step 2

Click the Workflows tab.

Step 3

Choose the VMPowerCycle workflow.

Step 4

Click the Schedule action.

Step 5

In the Schedule Workflow dialog, complete the fields as described in this table:

Name

Description

Recurrence Typedrop-down list

Choose Only once. You might choose other values in an actual production application.

Start Time date and time controls

Choose today's date and set a time a few minutes later than your current time.

Use ID text field

Type the administrator ID you are signed in as.

Step 6

Click Submit.

What to Do Next

Click the Workflow Schedules tab. The scheduled workflow is listed.

Check the service request queue at the time you specified in the Start Time control. See Viewing Service Requests. A service request is generated for the workflow you specified.

Using VM Action Policies

You can create a user VM action policy to apply to virtual data centers (VDCs). The policy contains workflows that can be run on VMs within that VDC.

Note

Only one VM action policy can be assigned per VDC.

To create a VM action policy, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the User VM Action Policy tab.

Step 3

Click Add.

Step 4

In the Add Policy: Create New Policy screen, complete the following fields:

Name

Description

Policy Name field

The policy name.

Policy Description field

A description of the policy.

Select No of Actions drop-down list

The number of actions defined by the policy. One action specifies a single workflow.

Step 5

Click Next.

Step 6

For each VM Action in the Add Policy: Add VM Actions screen, complete the following fields:

Name

Description

Action Label field

The label for the VM action. The action is available when you select a VM that is part of a virtual data center (VDC) to which the action policy is applied.

Workflow drop-down list

The workflow represented by this action.

Authorized User Types drop-down list

The user types authorized to run the policy workflows.

Step 7

Click Submit.

What to Do Next

After you create a User VM Action policy, as an administrator, you can choose this policy when you create a VDC. All VMs that belong to the VDC can then use the workflows specified in the action policy.

Chapter 6. Using Service Requests

This chapter contains the following sections:

- Viewing Service Requests

- Rolling Back a Service Request

- Resubmitting a Service Request

- Approving and Denying Service Requests

- Deleting Service Requests

Viewing Service Requests

You can view details of a service request, including its progress through the workflow, the service request log, objects created by the service request, and input and output of the service request workflow. To view service request details:

Step 1

On the menu bar, choose Organization > Service Requests.

Step 2

Choose the Service Requests tab.

Step 3

Choose a service request.

Step 4

Click View Details. The Service Request Status pane appears.

Step 5

Click the tabs along the top of the Service Request Status pane to examine different aspects of the service request:

- Workflow Status—Which tasks have succeeded or failed, and which task (if any) is currently running.

- Log—Debug, information, warning, and error messages generated by the workflow tasks.

- Objects Created and Modified—Details about objects created by the workflow, including the owning tenant, the account, and other information.

- Input/Output—Input and output of each workflow task. See Viewing Service Request Input and Output.

Step 6

Click Close.

- Viewing Service Request Input and Output

Viewing Service Request Input and Output

The Input/Output tab in the Service Request dialog displays a list of the values for each task in the workflow at the time of approval. There are four types of input or output that may be visible:

- Administrator input.

- Task input.

- Task output.

- A mapped input or output. In the case of a mapped input or output, the name of the other mapped output or input is shown in the Input/Output column. For example, a task input mapped to the EMAIL_ADDRESSES output from task SendEmail_94 would display SendEmail_94.EMAIL_ADDRESSES in the Input/Output column.

Note

The input and output values for a service request are viewable even if the underlying workflow has been deleted. However, in this case the input values cannot be edited.

SUMMARY STEPS

1.    On the menu bar, choose Organizations > Service Requests.

2.    Click a service request. The Input/Output table appears.

3.    Click the Input/Output tab. The input and output values of all the tasks in a workflow are accessible from this tab. The types of outputs appear in the Input/Output column.

4.    Click an arrow next to a folder icon in the left column to expand a task.

DETAILED STEPS

Step 1

On the menu bar, choose Organizations > Service Requests.

Step 2

Click a service request. The Input/Output table appears.

Step 3

Click the Input/Output tab. The input and output values of all the tasks in a workflow are accessible from this tab. The types of outputs appear in the Input/Output column.

Step 4

Click an arrow next to a folder icon in the left column to expand a task. The type, name, and value of each of the task's inputs and outputs is displayed in the table.

Rolling Back a Service Request

You can undo all or part of an executed workflow by using the Service Request Rollback feature. See Rollback for a description of how Service Request Rollback works.

You can roll back most workflow tasks that executed successfully. Exceptions:

- Some tasks are designed such that they cannot be rolled back.

- Rollback can be disabled for a task within a particular workflow. See the following discussion.

Any changes made by tasks that are not selected for rollback (for example, creating virtual resources) are not undone (for example, the virtual resources are not removed). If you choose to roll back an entire successful service request, all its workflow tasks are rolled back (with the previously listed exceptions).

Note

You can roll back a service request even if the underlying workflow has been deleted.

Step 1

On the menu bar, choose Organizations > Service Requests.

Step 2

Choose the Service Requests tab.

Step 3

Choose the service request that corresponds to the workflow that needs to be rolled back.

Step 4

(Optional) View the assets affected by the workflow. To view the workflow assets:

1. Click on the View Details action.

2. Select the Objects Created and Modified tab. The list shows all the objects created or modified by the workflow.

3. Click Close.

Step 5

Click Rollback Request.

Step 6

Initially, all tasks that can be rolled back are checked. Uncheck the check box next to the tasks that you do not want to roll back.
Tasks for which rollback has been disabled (see Configuring a Task in a Workflow) are unchecked. Checking these tasks to request their rollback results in an error when you submit the workflow rollback. If this happens, uncheck any tasks with disabled rollbacks and submit the workflow rollback again.

You can roll back subtasks at any level in the workflow's hierarchy of compound tasks. The Task Name column in the Rollback Service Request dialog displays the ancestry of each listed task.

Step 7

Click Submit.

What to Do Next

Rollback workflows start with Rollback in the Catalog/Workflow Name column of the Service Requests page. Right-click a rollback service request and choose View Details to examine its status.

Resubmitting a Service Request

You can resubmit all or part of a failed or cancelled service request.

Step 1

On the menu bar, choose Organizations > Service Requests.

Step 2

Click on a failed or cancelled service request.

Step 3

(Optional) Change user input values for the workflow before resubmitting the service request. You must have administrator privileges to change user inputs before resubmitting a workflow.
Note:
Only user workflow inputs can be changed. Admin inputs and task inputs cannot be changed before resubmitting.

To change the input values:

1. Click on the View Details action.

2. Select the Input/Output tab.

3. Enter new values for any of the inputs.

4. Click Close.

Step 4

Click on Resubmit Request. The Resubmit Service Request dialog appears.

Step 5

Select a subtask from the Resubmit Step drop-down menu. The workflow will be resubmitted beginning with this task.
You can select any task up to and including the subtask that caused the workflow to fail.

Note:
You can select nested compound tasks at any depth for the resubmitted task.

Step 6

(Optional) If all approvals succeeded before the workflow failed, bypass the approval tasks by selecting the Skip approvals if already approved checkbox.

Step 7

Click Submit.

Approving and Denying Service Requests

A workflow can include an approval task that requires a user, usually an administrator or someone with budget authority, to approve the workflow before it completes. To deal with workflows requiring your approval, do the following:

Before You Begin

A service request has been submitted with an Approval task that requires approval of a user ID that you own.

Step 1

Choose Organizations > My Approvals from the main menu.

Step 2

From the My Approvals page, choose an approval with status Pending in the My Approval Status column.

Step 3

(Optional). To view the service request details, choose the View Details action.

Step 4

Choose what to do with the request:

- To approve the service request and allow the workflow to resume execution, choose the Approve action.

- To deny the request but leave it in your approvals list in a rejected state, choose the Reject action.
Note:
If you reject an approval, the workflow continues with the On failure path from the approval task. The On failure path can be used, for example, to execute an email task to notify a user that the approval was rejected. Or, it can execute another approval task, giving a different user an opportunity to approve the task.

- To deny the request and remove it from your approvals list, choose the Cancel Request action. The workflow stops in a failed state at the approval task.

If you selected Approve or Reject, the Service Request screen appears. Continue to the next step.

If you selected Cancel Request, the Cancel Service Request dialog box appears. Skip the next step.

Step 5

(Optional). Type a comment in the Comment field of the Service Request screen.

Step 6

Click the button corresponding to your chosen action (Accept, Reject, or Cancel Request) to complete the action.

What to Do Next

To see the status of any workflow in your approval list, click the View Details action.

To see the status of a workflow that you cancelled or a workflow not in your approval list, choose Organizations > Service Requests from the main menu.

Deleting Service Requests

You can delete archived service requests from Cisco UCS Director. The deleted service requests are removed permanently from Cisco UCS Director.

You can enter archived service requests to delete in one of two ways:

- By selecting the service requests on the Archived Service Requests page and clicking the Delete Requests action.

- By selecting the Purge Requests action and typing the IDs of the archived service requests.

Both methods result in the permanent removal of the specified service requests. The only difference is the method of data entry.

You can delete only archived service requests. For information about archiving service requests, see the current release of the Cisco UCS Director Administration Guide. Because active service requests cannot be archived, you cannot delete service requests that are in progress, or that contain child service requests that are in progress.

You also cannot delete a service request that has a rollback that is in progress or that has failed. For example, say that you submit a rollback for service request (SR) 100 that generates a rollback service request SR 101. You cannot delete SR 100 while SR 101 is in progress. Furthermore, you cannot delete SR 100 if SR 101 failed.

To delete service requests, do the following:

Step 1

Navigate to Organizations > Service Requests.

Step 2

Click the Archived Service Requests tab.

Step 3

You can either enter service request IDs using the keyboard or choose service requests from the Archived Service Requests report.
To enter service request IDs, skip to the next step. To choose service requests instead, do the following:

1. Choose all the service requests that you want to delete.
Note:
Select multiple items as you would in any other application on your system. For example, in Windows, hold down the Ctrl key to choose more items or Shift to choose a range of items.

When you choose one or more service requests, the Delete Request action appears.

2. Click the Delete Request action.

3. In the Delete Request dialog, click Delete.

Step 4

To enter service requests, do the following:

1. Click Purge Requests.

2. In the Delete Request dialog, type the IDs of the service requests that you want to delete in the SR IDs text field. Use hyphens to indicate ranges of IDs and commas to separate ranges or individual IDs; for example: 101-111, 113, 116-118.

3. Click Delete.

Chapter 7. Managing Workflows

This chapter contains the following sections:

- Workflow Editing

- Exporting and Importing Cisco UCS Director Artifacts

- Workflow Version History

- Cloning a Workflow

- Saving a Picture of a Workflow

Workflow Editing

You can edit many features of an existing workflow. You can:

- Rename a workflow

- Reorder inputs

- Delete inputs

- Rename inputs

- Change an input from optional to mandatory (but not the reverse)

- Edit tasks in the workflow

You can also:

- Delete any or all versions of a single workflow

- Delete the default version or all versions of multiple workflows at one time

The following sections describe these procedures.

- Renaming Workflows

- Reordering Inputs

- Deleting Workflow Inputs

- Renaming Workflow Inputs

- Changing Input Optional or Required Status

- Editing a Task in an Existing Workflow

- Deleting a Workflow

- Deleting Multiple Workflows

Renaming Workflows

To rename a workflow, change its name field.

Note

All versions of the workflow are renamed.

You cannot rename a compound task.

Before You Begin

You have selected the workflow you want to rename and chosen the Edit action.

Step 1

In the Edit Workflow screen, enter the new name for the workflow in the Workflow Name field.

Step 2

Click Next.

Step 3

In the Add User Inputs screen, click Next.

Step 4

In the Add User Outputs screen, click Submit.

Reordering Inputs

After creating a workflow, you can change the order in which workflow user inputs are processed when the workflow is executed.

Before You Begin

You have selected the workflow in which you want to reorder the inputs and have chosen the Edit action.

Step 1

In the Edit Workflow Details screen, click Next to advance to the input screen.

Step 2

In the Edit User Inputs screen, choose an input from the input table.

Step 3

Click the Up Arrow icon or Down Arrow icon to move the input up or down in the input order.
Alternatively, you can drag and drop an input to a different place in the list.

Step 4

Click Next.

Step 5

In the Edit Workflow Outputs screen, click Submit.

Deleting Workflow Inputs

You can delete one or more inputs while editing an existing workflow.

Note

You can also delete inputs in a cloned workflow.

To delete inputs from an opened workflow, do the following:

Before You Begin

Navigate to Edit User Inputs page:

1. Select the workflow from which you want to delete inputs.

2. Click Edit to open the Edit Workflow window.

3. Click Next to move to the Edit User Inputs page.

Alternatively, while editing a task, click Manage Workflow User Inputs on the User Input Mapping page.

Step 1

In the Edit Workflow Inputs list, select the inputs that you want to delete.
To select multiple inputs from the list, hold down the <Shift> key (for a range of items) or <Ctrl> key (to select individual items).

Step 2

Click the Delete (X) icon at the top of the list.

Step 3

In the Delete Entry popup dialog, click Submit.

What to Do Next

Click Next to move to the Edit User Outputs page, then click Submit.

Renaming Workflow Inputs

You can rename inputs while editing an existing workflow.

To rename inputs from an opened workflow, do the following:

Before You Begin

Navigate to the Edit User Inputs page:

1. Select the workflow in which you want to rename inputs.

2. Click Edit to open the Edit Workflow window.

3. Click Next to move to the Edit User Inputs page.

Alternatively, while editing a task, click Manage Workflow User Inputs on the User Input Mapping page.

Step 1

In the Edit Workflow Inputs list, select an input that you want to rename.

Step 2

Click the Edit (pencil) icon at the top of the list.

Step 3

In the Edit Entry popup dialog, replace the name in the Input Label text field.

Step 4

Click Submit.

Step 5

Repeat the previous steps to edit another input.

What to Do Next

Click Next to move to the Edit User Outputs page, then click Submit.

Changing Input Optional or Required Status

You can change the optionality (optional or required status) of workflow inputs.

Note

You cannot map an optional workflow input to a mandatory task input. Similarly, you cannot change an input from mandatory to optional if it is mapped to a mandatory task input.

Before You Begin

Select the workflow you want to edit and choose the Edit action.

Step 1

In the Edit Workflow window, click Next to advance to the Modify User Inputs screen.

Step 2

In the inputs table, double-click an input that you want to edit.

Step 3

In the Edit Entry dialog box, check or uncheck the Optional check box to make the input optional or required, respectively, at the time of execution.
Note:
You cannot make a workflow user input optional if it is mapped to a mandatory task input.

Step 4

Click Submit.

Step 5

In the Edit Workflow: Edit Workflow Inputs window, click Next.

Step 6

In the Edit Workflow: Edit Workflow Outputs window, click Submit.

Editing a Task in an Existing Workflow

You can edit a task in an existing workflow. The change is local to the workflow and version containing the edited task. For example, if you edit task A in version 0 of workflow X, the task remains unchanged in workflow Y and in version 1 of workflow X.

Step 1

Open a workflow in the Workflow Designer.

Step 2

In the workflow display, double-click the task that you want to edit. The Edit Task window appears.

Step 3

In the Task Information screen, you can edit the following fields:

Name

Description

Task Name field

You cannot change the name of the task.

Task Category drop-down list

You cannot change the task category.

Task Type drop-down list

You cannot change the task type.

Comment field

You can change or add to the comment.

Retry Execution check box

You can check or uncheck this box. If the box is checked, Retry Count and Retry Frequency controls appear.

Disable Rollback check box

You can check or uncheck this box. If the box is checked, the task is unchecked in the Rollback Service Request dialog and cannot be rolled back; see Rolling Back a Service Request.

If the task does not support rollback, checking this box has no effect.

Retry Count drop-down list

The number of times (up to 5) to retry the task on failure.

Retry Frequency field

A comma-separated list of integers specifying how many seconds to wait between retries. For example, if you selected a retry count of three, enter 1, 10, 60 to retry after one, 10, and 60 seconds, respectively.

Step 4

Click Next.

Step 5

On the User Input Mappings page, you can edit the following fields:

Name

Description

Manage Workflow User Inputs button

Click this button to add to or edit the workflow user inputs.

Task Input headings

Each task input is displayed as a heading on the remainder of this page. The input is labeled (Mandatory) if it required.

Map to User Input check box

Check this box to populate the task input from a workflow user input at runtime.

User Input drop-down list

This drop-down list appears if you check the Map to User Input check box. Select the workflow user input to map to the task input.

Step 6

Click Next.

Step 7

On the Task Input page, you can edit the following fields:

Name

Description

(input label) control

Each task input that was not mapped to a user input on the previous page is displayed with an appropriate input control (text field, drop-down list, and so on). Use the input controls to specify the value. Optional inputs can be left blank.

Step 8

In the User Output Mapping screen, you can edit the following fields:

Name

Description

Task Output heading

Each task output is displayed as a heading on this page. The output is labeled (Mandatory) if it required. The output heading labels are assigned automatically and cannot be modified.

Map to User Output check box

Check this box to populate a workflow user output from the task output at runtime.

User Output drop-down list

This drop-down list appears if you check the Map to User Output check box. Select the workflow user output to map to the task output.

Step 9

Click Submit.

Deleting a Workflow

You can delete any or all versions of a workflow.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

Choose Delete from the task bar or from the actions drop-down list.

Step 4

In the Delete Workflow(s) dialog, choose the versions that you want to delete. To choose all versions for deletion, check the check box at the top of the list.

Step 5

Click the Delete button.

Deleting Multiple Workflows

You can delete more than one workflow at a time.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

Choose all the workflow you want to delete.
Note:
Select multiple items as you would in any other application on your system. For example, in Windows, hold down the Ctrl key to choose more items or Shift to choose a range of items.

Step 4

Choose Delete All from the task bar or from the actions drop-down list.

Step 5

In the Delete Workflow dialog, check the Delete All Versions check box if you want to delete all versions of the selected workflows. Otherwise only the default version is deleted.

Step 6

Click the Delete button.

Exporting and Importing Cisco UCS Director Artifacts

You can export and import workflows, custom tasks, script modules, and activities in Cisco UCS Director. This is useful if, for example, you want to:

- Move or copy workflows or other entities to different Cisco UCS Director instances.

- Back up or store entities.

- Use templates to standardize workflows.

Exporting and Importing Artifact Files

Cisco UCS Director artifacts are exported from and imported to Cisco UCS Director in a single package. The you exported or imported file has a.wfdx extension and is an XML file containing a serialized representation of the objects. The file contains at least one of the following:

- One or more workflows

- One or more custom tasks

- One or more script modules

- One or more activities

For example, you might import a file that contains only a single custom task; or a file that contains several workflows, a script module, and a few activities; and so on.

Exporting and Importing Workflows as Templates

You can export and import workflows as templates.

When you export a template, all of the tasks within the workflow are retained. When you create a new workflow using a template, task inputs that have been mapped to workflow inputs cannot be modified. However, you can modify inputs which have not been mapped.

- Exporting Workflows, Custom Tasks, Script Modules, and Activities

- Importing Workflows, Custom Tasks, Script Modules, and Activities

- Workflow Templates

Exporting Workflows, Custom Tasks, Script Modules, and Activities

To export artifacts from Cisco UCS Director, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

In the Orchestration pane, click the Workflows tab.

Step 3

On the Workflows tab, click Export.

Step 4

In the Select Workflows screen, select the workflows that you want to export.

Step 5

Click Next.

Step 6

In the Select Custom Tasks screen, select the custom tasks that you want to export.

Step 7

Click Next.

Step 8

In the Export: Select Script Modules screen, select the script modules that you want to export.

Step 9

Click Next.

Step 10

In the Export: Select Activities screen, select the activities that you want to export.

Step 11

In the Export: Confirmation screen, complete the following fields:

Name

Description

Exported By text field

Your name or a note on who is responsible for the export.

Comments text area

Comments about this export.

Exported File Name text field

The name of the file on your local system. Type only the base filename; the file type extension (.wfdx) is appended automatically.

Step 12

Click Export.

You are prompted to save the file.

Importing Workflows, Custom Tasks, Script Modules, and Activities

To import artifacts into Cisco UCS Director, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

In the Orchestration pane, click the Workflows tab.

Step 3

Click the Import action.

Step 4

In the Import dialog box, click Upload.

Step 5

In the File Upload dialog, click Click and select a file from your computer.

Step 6

Select the import file. Cisco UCS Director import and export files have a .wfdx file extension. When the file is uploaded, the File Upload dialog displays File ready for use.

Step 7

Dismiss the File Upload dialog.

Step 8

Click Next. The Import dialog displays a list of Cisco UCS Director objects contained in the uploaded file.

Step 9

(Optional) Specify how objects are handled if they duplicate names already in the workflow folder. In the Import dialog box, complete the following fields:

Name

Description

Workflows drop-down list

Choose from the following options to specify how identically named workflows are handled:

- Replace—Replace the existing workflow with the imported workflow.

- Keep Both—Import the workflow as a new version.

- Skip—Do not import the workflow.

Custom Tasks drop-down list

Choose from the following options to specify how identically named custom tasks are handled:

- Replace

- Keep Both

- Skip

Script Modules drop-down list

Choose from the following options to specify how identically named script modules are handled:

- Replace

- Keep Both

- Skip

Activities drop-down list

Choose from the following options to specify how identically named activities are handled:

- Replace

- Keep Both

- Skip

Import Workflows to Folder check box

Check this check box to import the workflows. If you do not check the box and if no existing version of a workflow exists, that workflow is not imported.

Select Folder drop-down list

Choose a folder into which to import the workflows. If you chose [New Folder..] in the drop-down list, the New Folder field appears.

New Folder field

Enter the name of the new folder to create as your import folder.

Step 10

Click Import.

Workflow Templates

A workflow template is like an outline of a workflow. It contains placeholders for all the tasks in the workflow, but is not executable.

A workflow template is useful when you want to import a workflow to a different Cisco UCS Director instance, especially if the workflow is large or contains custom tasks.

A workflow template contains the following elements:

- Task names. Only the names are exported; the tasks themselves must exist in the Cisco UCS Director environment in order to execute.

- Workflow structure (connections between tasks).

- Input names.

A workflow template does not contain these elements:

- Custom tasks. Since only task names are exported in a template, you must import custom tasks in the new Cisco UCS Director environment in order for them to execute.

- Admin input values. Since the elements referred to by input values are unlikely to exist in the new Cisco UCS Director environment, input values must be redefined.

- Exporting Workflows as Templates

- Importing a Workflow Template

- Creating a Workflow from a Template

- Predefined Templates

Exporting Workflows as Templates

You can export a workflow as a template. To export a workflow as a template:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

Choose a workflow.

Step 4

Click Export As Template.

Step 5

In the Export as Template dialog, complete the following fields:

Name

Description

Template Name field

The name for the template.

Description field

A description of the template.

Step 6

Click Submit. You are prompted to save the template to your system.
Note:
The template is saved under a system-generated filename. The template name you assign is for display in Cisco UCS Director only.

Importing a Workflow Template

To import a workflow template:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflow Templates tab.

Step 3

Click the Import action.

Step 4

In the Import dialog box, click Upload.

Step 5

In the File Upload dialog, click Click and select a file from your computer.

Step 6

Select the template file. Cisco UCS Director template files have a .wft file extension. When the file is uploaded, the File Upload dialog displays File ready for use.

Step 7

Dismiss the File Upload dialog.

Step 8

In the Import Template dialog, click Submit.

The template appears on the Workflow Templates page.

Creating a Workflow from a Template

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflow Templates tab.

Step 3

Choose a template.

Step 4

Click Create Workflow.

Step 5

In the Overview screen, complete the following fields:

Name

Description

Name text field

The name of the workflow to be created.

Description text area

An optional description for the workflow.

Step 6

Click Next.

Step 7

Click through the remaining pages of the Create Workflow from Template wizard. You can change any editable task-specific inputs that appear.

Step 8

Click Submit.

The workflow is created in the Template Workflows folder on the Workflows page.

What to Do Next

Open the workflow in the Workflow Designer and configure it to work in its new environment.

Predefined Templates

Cisco UCS Director installs with the following predefined templates. The templates are available, along with any user-imported templates, in the Policies > Orchestration > Workflow Templates tab.

Name

Purpose

Description

Customer Onboarding template

Customer onboarding in a secure multitenancy setting

The workflow does the following:

- Creates a virtual data center (VDC)

- Generates a VLAN from the selected VLAN policy

- Creates a VLAN on the selected Cisco Nexus 5000 Series switches

- Creates a port profile on selected Nexus 1000v Series switches

- Creates a VLAN interface

- Creates flexible volume

- Creates and establishes a vFiler on the controller

- Mounts the storage as a data store on a selected host node

Deploy ESXi Host template

Deployment of a new blade as an ESXi Host on a VMware (vCenter) account

The workflow does the following:

- Creates a service profile

- Associates the service profile to a selected server

- Configures SAN zones on a Cisco Nexus 5000 Series switch

- Establishes a PXE boot

- Monitors PXE booting and registers the host with a selected VMware (vCenter) account

Deploy ESXi Host with ONTAP template

Deployment of a new blade as an ESXi Host on a VMware (vCenter) account.

Workflow does the following:

- Creates a service profile

- Associates the service profile to a selected server

- Configures SAN zones on a Cisco Nexus 5000 Series switch

- Establishes a PXE boot

- Monitors PXE booting and registers the host with a selected VMware (vCenter) account

Deploy ESXi Host of Local Storage (without a Cisco Nexus 1000v Series switch) template

Deployment of a new blade as an ESXi local storage host (without using a Cisco Nexus 1000v Series switch) on a VMware (vCenter) account

The workflow does the following:

- Creates a service profile

- Associates the service profile to a selected server

- Configures SAN Zones on a Cisco Nexus 5000 Series switch

- Establishes a PXE boot

- Monitors PXE booting and registers the host with a selected VMware (vCenter) account

Attach VLAN to Storage Controller template

Attaching a NetApp storage controller's Ethernet ports to a new VLAN

The workflow does the following:

- Generates a VLAN from the selected VLAN policy

- Creates a VLAN on the selected devices

- Creates a VLAN interface

- Creates a vFiler on the controller

Workflow Version History

Cisco UCS Director provides a set of features for managing versions of a workflow. For an introduction to workflow versioning, see Workflow Versioning.

The following sections discuss how to manage workflow versions.

- Creating a New Version of a Workflow

- Choosing the Default Version of a Workflow

- Managing Versions of a Compound Task

Creating a New Version of a Workflow

You can create a new version of a workflow. You can then modify the new version without changing the old version.

Before You Begin

You have an existing workflow that you want to modify.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

Choose the workflow to duplicate.

Step 4

Click the Create New Version action.

Step 5

In the Create New Version screen, complete the following fields:

Name

Description

Version Label field

The label for the version. The default label for a new workflow is zero, so consider labeling new versions numerically starting from one.

Description field

A description for the version.

Step 6

Click Submit. The new version opens in the Workflow Designer.

Step 7

In Workflow Designer, complete your changes for the workflow.

Step 8

Click Close.

If the Manage Versions settings specify Set latest version as default, the new version becomes the default version. The Workflows page displays the new version of the workflow under the Version column.

If the Manage Version settings specify Set selected version as default, the new version is created but the default version does not change. See Choosing the Default Version of a Workflow.

Choosing the Default Version of a Workflow

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflows tab.

Step 3

Right click the workflow and choose Manage Versions.

Step 4

In the Manage Versions screen, complete the following fields:

Name

Description

Show latest version checkbox

Check this checkbox to set the default version of a workflow to be the last version that was created. The default version of a workflow is displayed in the Workflows page. If you create a new version of a workflow, the new version becomes the default.

For example, if the latest version of a workflow is X.0, the Version Label column in the Workflows page displays X.0. If you then create a version X.1, the Version Label column displays X.1.

Set default version checkbox

Check this checkbox to set the default version of a workflow to be the version that you select. The default version of a workflow is displayed in the Workflows page. If you create a new version of a workflow, your selected version remains the default.

For example, if the latest version of a workflow is X.0, the Version Label column in the Workflows page displays X.0. If you then create a version X.1, the Version Label column remains X.0.

Version list of values

If you selected the Set default version checkbox, check one version from the list to be the default version.

Step 5

Click Submit.

Managing Versions of a Compound Task

When you update a compound task, the new version of the compound task replaces the old one in all workflows that use the compound task.

However, it is possible for some versions of a workflow to be compound tasks while other versions of the same workflow are not. Normally, the behavior of a workflow is defined by the workflow's default version, but this is sometimes not the case with compound tasks.

If the default version of a workflow is not a compound task, then when the workflow is called as a compound task the system uses the most recent version of the workflow that is defined as a compound task. This can be confusing. The following example illustrates this behavior.

Before You Begin

1. Create a compound task called CT. Note that in the Workflow tab, the Version Label for CT is shown as 0. We will refer to this version of CT as CTv0.

2. Include the compound task in a workflow called WF.

3. Validate the workflow WF. Validation should pass.

Step 1

Save CTv0 as a normal (non-compound-task) workflow:

1. Go to Policies > Orchestration > Workflow.

2. Choose the compound task workflow CTv0.

3. Click Edit Workflow.

4. Uncheck the Save as Compound Task checkbox.

5. Click through to the Edit User Outputs page and click Submit.

Step 2

In the Workflow Designer, validate WF.

1. Choose the Workflows tab.

2. Choose the workflow WF.

3. Click Workflow Designer.

4. In the Workflow Designer page, click Validate Workflow.

Validation fails with the message The task "Compound add user" does not exist anymore.

Step 3

Create a new version of CT (CTv1).

1. Choose the Workflows tab.

2. Choose the workflow CTv0.

3. Click Create New Version.

4. In the Create New Version dialog, enter the required fields:

- Version Label - Something recognizable, for example v1.

- Description - Any description.

5. Click Submit.

6. When the Workflow Designer comes up, click Close.

7. Click Edit.

8. Verify that for CTv1, the Save as Compound Task checkbox is unchecked.

9. Close the Edit Workflow page.

Step 4

Validate WF again, as in Step 2. Validation fails with the message The task "Compound add user" does not exist anymore.

Step 5

Make CTv1 a compound task.

1. Choose the Workflows tab.

2. Choose the workflow CT.

3. Click Edit Workflow.

4. Check the Save as Compound Task checkbox.

5. Click through to the Edit User Outputs page and click Submit.

Step 6

Validate WF again. Validation is successful.

Step 7

Change the default version of CT back to CTv0.

1. Choose the Workflows tab.

2. Choose the workflow CT.

3. Click Manage Versions.

4. In the Manage Versions dialog, uncheck Set Latest Version as Default.

5. Check Set Selected Version as Default.

6. In the table, check CTv0.

7. Click Submit.

Note that in the Workflows tab Version Label is now 0, indicating that CTv0 is the default version of CT.

Step 8

Validate WF again. Validation is successful. Note that WF is using CTv1 as the compound task, even though CTv0 is the default. Be aware that this can cause confusion if you have more than one version of a workflow that is used as a compound task.

Cloning a Workflow

You can clone a workflow. The cloned workflow is identical to the original workflow. You can edit the new workflow immediately. You might do this, for example, to create a workflow that is similar to the original workflow but which has different inputs. The new workflow has a new, separate version history.

Before You Begin

Navigate to Policies > Orchestration and select the Workflows tab.

Step 1

Select the workflow you want to clone.

Step 2

Click Clone. The Clone Workflow window comes up.

Step 3

Edit the workflow details, inputs, and outputs. See Creating a Workflow. You must enter a new name for the workflow.

Step 4

Click Next to proceed to the Workflow User Inputs screen.

Step 5

Edit the workflow user inputs.

Saving a Picture of a Workflow

You can create a graphics image of a workflow. To capture an image, do the following:

Step 1

On the menu bar, choose Policies > Organization.

Step 2

Choose the Workflows tab.

Step 3

Choose a workflow.

Step 4

Click on Workflow Designer.

Step 5

From within the Workflow Designer window click the Full View icon.

Step 6

Click Export as Image. You are prompted to save the image file.

Step 7

Choose a directory (if applicable) and click Save.

The saved file is named workflow_nnn.png, where nnn is the workflow ID number in Cisco UCS Director. The workflow ID number is visible in the upper left corner of the Workflow Designer next to the workflow name.

Chapter 8. Customizing Workflow Components

This chapter contains the following sections:

- Creating a Compound Task

- Creating Custom Approvals

- Creating Custom Inputs

- Macros

Creating a Compound Task

A compound task is a workflow that functions as a single task. A compound task, like any other task, is atomic; its component tasks are hidden.

You create a compound task by saving a workflow as a compound task when you create or edit the workflow. Do this, for example, if you find yourself building the same series of tasks into several different workflows.

You can define a simple workflow and save it as a compound task, then define another workflow that incorporates the compound task. You can use this pattern to define increasingly complex workflows.

To save an existing workflow as a compound task, do the following:

Note

To create a new compound task from scratch, see Creating a Workflow

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Workflow tab.

Step 3

Select a workflow to save as a compound task.

Step 4

Click Edit.

Step 5

Check the Save as Compound Task check box.

Step 6

If you want all of the workflow's task outputs available as output of the compound task, click the Publish Task outputs as Compound Task outputs check box.

Step 7

Click Next.

Step 8

On the Add User Inputs screen, click Next.

Step 9

On the Add User Outputs screen, click Submit.

The new compound task is available in the Compound Task folder when you open the Workflow Designer.

- Example: Creating a Compound Task

Example: Creating a Compound Task

This example demonstrates repeating a workflow task for elements in a list.

Before You Begin

Create the example workflow as described in Example: Creating a Workflow.

Step 1

Navigate to Policies > Orchestration.

Step 2

Click the Workflows tab.

Step 3

Locate and select the PowerCycleVM workflow you created in Example: Creating a Workflow.

Step 4

Click Edit.

Step 5

In the Edit Workflow Details window, check the Save as Compound Task check box.
Note:
None of the tasks has an output, so ignore the Publish Task Outputs as Compound Task outputs check box. The workflow has nothing to do with system startup of Cisco UCS Director, so ignore also the Always execute during System initialization check box.

Step 6

Click through to the Edit Workflow Output page.

Step 7

Click Submit.

What to Do Next

Include the custom task in other workflows. For example, you can put this task before the Completed (Failed) task of workflows that modify to remotely hosted VMs. Then, the VM restarts if a modification fails.

Creating Custom Approvals

You can create custom approval tasks that allow approvers to enter input values at the time of workflow execution.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Choose the Custom Approval Tasks tab.

Step 3

Click Add.

Step 4

In the Add Inputs screen, complete the following fields:

Name

Description

Approval Task Name field

The name of the approval task as it appears in the Workflow Designer.

Approval Task Description field

The description of the approval task (optional).

Step 5

Click the Add Input Field button.

Step 6

Under the User Input heading for the new input field, complete the following fields:

Name

Description

Input Label field

The label for the input (supplied by the approver of the task).

Input Description field

A description of the input.

Input Type drop-down

The data type of the input.

Optional Input check box

If checked, the administrator must provide a default value for the input. The approver is not required to provide input.

Step 7

Repeat the previous two steps to add as many inputs as needed.

Step 8

Click Submit.

What to Do Next

You can now include the custom task in a workflow.

Creating Custom Inputs

You can create custom input types to use as workflow inputs. Custom input types are based on an existing input type. They are defined by filter criteria or by a selection set that further narrows the possible values of the input.

Step 1

On the menu bar, choosePolicies > Orchestration.

Step 2

Click the Custom Workflow Inputs tab.

Step 3

Click Add.

Step 4

In the Add Custom Workflow Input screen, complete the following fields:

Name

Description

Custom Input Type Name field

The input name.

Input Type button

Pressing this button brings up a list of existing input types. From the list, choose an input type on which to base your input type.

Filter check boxes

Depending on your choice of input type, one or more of the following filter types is available:

- Input Filter—A text field. Type a text filter string.

- Input List—A list of values. Choose which existing values are valid instances for this input.

- Input LOV—Define a list of allowable name-value pairs for the input.

Note:
The Label field and Value field descriptions should match.

- Input Range—A text field. Type a range of valid character values.

- Validated Input—Choose a validator type from the table.

Step 5

Click the (+) Add icon.

Step 6

Click Submit.

The new input type is added to the Custom Workflow Types page. The new input type is available for selection when defining workflow and task inputs.

Macros

Macro variables, or macros, are variables that you can use within Cisco UCS Director Orchestrator.

Macros enable you to include several types of variable system information in two places:

- In task input variables inside a workflow, where you can access such information as:

- Workflow inputs and task outputs

- Service request IDs

- VM information such as ID, name, IP address, and power state

- In VM names, where you can access such information as:

- User information such as group and user IDs

- Configuration information such as catalog and system profile

- Deployment information such as cloud name and location

- Orchestration Macros

- VM Annotations

- List of VM Macros and VM Annotations

Orchestration Macros

Several macros can be accessed in the context of a workflow by workflow tasks. When you create a Cisco UCS Director workflow, you can use macros in any of the workflow's task inputs. An input field can contain any combination of text and macros. During execution of the workflow, Cisco UCS Director Orchestrator substitutes the macros' values into each task's inputs before executing the task. Macros available for use in task inputs are described in the following sections.

- Input and Output Macros

- Service Request Macros

- Virtual Machine Macros

Input and Output Macros

Any workflow-level input or previous task output can be used as a macro in a subsequent task. For example, consider a workflow that has two inputs labeled Enter Disk Size and Max Snapshots. Suppose that the workflow has two tasks with IDs task1 and task2 (arranged so that task1 executes first). Any input values to task1 or task2 that takes free-form input can use the following two macros:

- ${Enter Disk Size}

- ${Max Snapshots}

Note

Macros consist of a dollar sign ($) followed by the macro name in curly braces ({}). The macro name for a workflow input is the same as the label associated with that workflow input.

Also the second task, task2, can use the output of task1. If task1 has two output variables, OUTPUT_VOLUME_NAME and OUTPUT_VOLUME_SIZE, then task2 can use the following macros to capture their values in its inputs:

- ${task1.OUTPUT_VOLUME_NAME}

- ${task1.OUTPUT_VOLUME_SIZE}

Note

The macro name for a task output is the task name, followed by a period, followed by the task output name: ${taskName.outputName}.

Service Request Macros

In addition to workflow inputs and task outputs, the following macros representing service requests are available:

- ${SR_ID}—The ID of the current service request

- ${PARENT_SR_ID}—The ID of the service request that is the parent of the current service request.(Available only if the current service request has a parent.)

Virtual Machine Macros

For workflows that are executed in the context of a VM, more VM macros are available. VM macros cannot be used in a non-VM context.

For the full list of VM macros, see List of VM Macros and VM Annotations.

VM Annotations

VM annotations represent information about a VM. You add these variables to a VMware system policy if you choose to define VM annotations in that policy. The output from these variables displays in the Annotations field of the VM in VMware vCenter.

For the full list of VM annotations, see List of VM Macros and VM Annotations.

List of VM Macros and VM Annotations

The syntax that you use for VM macros can be different from the syntax used for VM annotations. In addition, more variables are available for VM macros than for VM annotations. The following table shows the correct syntax for VM macros and for VM annotations. If a cell contains N/A, that variable is not available in the context.

For information about the variables that you can use in the VM Name Template and VM Host Name Template fields of the system policy, see the Cisco UCS Director Administration Guide.

Variables

VM Macros for Orchestration Workflows

VM Annotations for System Policies

VM name

${VM_NAME}

${VMNAME}

VM IP address

${VM_IPADDRESS}

N/A

VM state (can be either on or off)

${VM_STATE}

N/A

VM state details (can be either power-on or ppower-off)

${VM_STATE_DETAILS}

N/A

ESX server or host node that hosts the VM

${VM_PARENT}

N/A

Cloud used for VM provisioning

${VM_CLOUD}

${CLOUD_NAME}

Type of cloud

N/A

${CLOUD_TYPE}

VM hostname

${VM_HOSTNAME}

N/A

Name of the group to which the VM belongs

${VM_GROUP_NAME}

${GROUP_NAME}

Full name of the group

N/A

${FULL_GROUP_NAME}

ID of the group

${VM_GROUP_ID}

N/A

Name of the parent group, if one exists

N/A

${GROUP_PARENT}

ID of the catalog used to provision the VM

${VM_CATALOG_ID}

N/A

Name of the catalog used to provision the VM

N/A

${CATALOG_NAME}

VM ID

${VM_ID}

N/A

Service request ID for the VM

${VM_SR_ID}

${SR_ID}

Comments from the user who requested the VM

${VM_COMMENTS}

${COMMENTS}

Virtual data center name

${VM_VDC_NAME}

N/A

Virtual data center ID

${VM_VDC_ID}

N/A

Type of VM

${VM_TYPE}

N/A

Scheduled termination of the VM

${VM_SCHED_TERM}

N/A

Location specified in the account

N/A

${LOCATION}

Cost center for the VM

N/A

${COST_CENTER}

Current time in milliseconds converted to a unique ID for the VM

N/A

${UNIQUE_ID}

User who requested the VM

N/A

${USER}

Full name of the user who requested the VM

N/A

${FULL_USER_NAME}

Appcode from the catalog

N/A

${APPCODE}

Name of the system policy associated with the application category

N/A

${PROFILE_NAME}

Chapter 9. Using Activities

This chapter contains the following sections:

- Activities

- Creating an Activity

- Associating an Activity with a Workflow

- Adding an Activity to a Workflow

- Importing and Exporting Activities

- Deleting an Activity

Activities

Activities provide a layer of abstraction to workflow input variables. The abstraction helps you to efficiently execute any administration scenario (such as tenant onboarding or application deployment) by separating the specification of a workflow from its actual implementation. Using activities, you can do the following:

- Define the input properties for a workflow and associate those properties with one or more workflows. Then, depending upon a matching condition, the activity triggers the correct workflow.

- Use an activity as a workflow task, making the task usable in multiple similar but differently implemented use case scenarios.

- An activity can be either triggered programmatically or by providing inputs dynamically.

Creating an Activity

You create an activity by defining inputs and outputs. To create an activity:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Activities tab.

Step 3

Click Add.

Step 4

In the Add Activity dialog box, complete the following fields:

Name

Description

Name field

The activity name.

Label field

The label for the activity.

Description field

A description of the activity.

Step 5

Click Next.

Step 6

In the Add User Inputs screen, click the + icon to add workflow input properties.

1. In the Add Entry to Input Fields dialog box, complete the following fields:

Name

Description

Input Name field

The name of the activity workflow input.

Input Label field

The label for the activity workflow input.

Optional check box

Check the check box to make the input optional during workflow execution.

Input Type field

Click Select. In the Select dialog box, choose the input type.

2. Click Submit.

Step 7

Click Next.

Step 8

In the Add User Outputs screen, click the + icon to add workflow output properties.

1. In the Add Entry to Output Fields dialog box, complete the following fields:

Name

Description

Output Name field

The name of the activity workflow output.

Output Label field

The label for the activity workflow output.

Output Type field

Click Select. In the Select dialog box, choose the output type.

2. Click Submit.

Step 9

Click Submit.

Associating an Activity with a Workflow

You can associate an activity with one or more workflows to run the activity as part of the workflow. The associated activity is displayed as a custom workflow task in the System Activity Tasks folder of the Workflow Designer.

Before You Begin

You have an activity and at least one workflow that is to include the activity. For more information about how to create an activity, see Creating an Activity.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Workflows tab.

Step 3

Click Add Workflow.

Step 4

In the Add Workflow dialog box, complete the following fields:

Name

Description

Workflow Name field

The workflow name.
Note:
Workflow names cannot contain the following characters: \, ", %, &, ', *, +, ,, ., /, :, ;, <, =, >, ?, ^, |.

Description field

A description of the workflow.

Workflow Context drop-down list

Choose the context in which the workflow can be used. Orchestrator supports the following options:

- Any—Enables you to use the workflow in any context.

- Selected VM—Enables you to execute the workflow only when you choose a VM.

Save as Compound Task check box

Check the check box to define the workflow as a compound task.

Place in New Folder check box

Check the check box to assign the workflow to a new folder. The Folder Name field replaces the Select Folder drop-down list. Type a name for the new folder.

Select Folder drop-down list

Choose the folder into which you want to place the workflow.

Notify status of execution to initiating user check box

Check the check box to notify the user through email of the execution status of the workflow. If checked, enter the additional email addresses in the Additional User(s) to send Email Notification field. The execution status for the workflow can be one of the following:

- Completed status

- Failed execution status

- Cancelled execution status

Step 5

Click Next.

Step 6

In the Add User Inputs screen, check the Associate to Activity check box.

Step 7

From the Activity drop-down list, choose an activity. The user input table is updated based on the selected activity.

Step 8

Click Next.
In the Add User Outputs screen, the user outputs are displayed based on the selected activity.

Step 9

Click Submit. A workflow is created and is available in the Workflows tab.

Adding an Activity to a Workflow

The activity that is associated with one or more workflows is displayed as a custom workflow task in the System Activity Tasks folder of the Workflow Designer. Drag-and-drop the selected activity onto the Workflow Designer window to add it to a workflow. Define the condition for controlling execution of workflows associated with an activity in the Context Input table of the workflow.

Before You Begin

Associate an activity with a workflow so that the activity is displayed as a custom workflow task in the System Activity Tasks folder of the Workflow Designer. For more information about how to associate an activity with a workflow, see Creating an Activity.

Open the workflow in the Workflow Designer.

Step 1

Choose the activity from the System Activity Tasks folder.

Step 2

Drag-and-drop the selected activity onto the Workflow Designer window. The Add Task dialog box appears.

Step 3

In the Task Information screen, complete the following fields:

Name

Description

Task Name field

The name of the task.

Task Category field

The name of the task category (preselected information).

Task Type field

The name of the type of task (preselected information).

Comments field

Enter more task information.

Retry Execution check box

Check the check box to retry a task (later) if the task fails. This feature is useful when the state of a resource is not available and a retrial of the task depends on the state.

Retry Count drop-down list

Choose the number of retry attempts.

Retry Frequency drop-down list

Choose the duration between retry attempts. The workflow remains on the failed task until the task succeeds or until it fails Retry Frequency number of times. It then proceeds to the next task or completion of the workflow.

Step 4

Click Next. The User Input Mapping screen displays the inputs that are defined for the activity.

Step 5

Check the Map to User Input check box to use the corresponding input in the workflow.

Step 6

In the Context Input table, click the + icon to add a contextual input:

1. In the Add Entry to Input Fields dialog box, complete the following fields:

Name

Description

User Inputs drop-down list

Choose an input to which to apply the condition.

Minimum Condition drop-down list

Choose the condition that you want to apply to the input.

Value field

The value set for the condition.

Associated Workflow drop-down list

Choose a workflow to execute when the input satisfies the selected condition.

2. Click Next.

Step 7

Click Revalidate to validate the current values.

Step 8

Click Next. The User Output Mapping screen displays the outputs that are defined for the activity.

Step 9

Check the Map to User Output check box to use the corresponding output in the workflow.

Step 10

Click Submit.

Importing and Exporting Activities

You can import and export activities using the Import and Export actions you use to import and export workflows, custom tasks, and script modules.

To import an activity, see Importing Workflows, Custom Tasks, Script Modules, and Activities.

To export an activity, see Exporting Workflows, Custom Tasks, Script Modules, and Activities.

Deleting an Activity

You can delete an activity.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Activities tab.

Step 3

Select the activity to delete.

Step 4

Click Delete. The Activity dialog box appears to confirm deletion of the activity.

Step 5

Click Delete.

Chapter 10. Using Script Modules

This chapter contains the following sections:

- Using Script Modules

- Adding Script Modules

- Adding Libraries

- Jar Files

- Lists of Values

- Tabular Reports

- Context Mapping

- Importing and Exporting Script Modules

Using Script Modules

A script module is essentially a container for custom scripts, jar files, and input controls. The contents of script modules enable you to perform customized actions such as adding library scripts that can be integrated with custom workflow tasks. You can export a script module and import it to a different appliance. Registered scripts in the imported module are available in the new appliance.

The following table describes the actions you can perform using script modules:

Task

See

Adding script modules

Adding Script Modules

Adding libraries

Adding Libraries

Adding jars

Adding Jar Files

Adding Lists of Values (LOVs)

Lists of Values

Adding Tabular Reports

Tabular Reports

Adding Context Mappings

Context Mapping

Exporting script modules

Exporting Workflows, Custom Tasks, Script Modules, and Activities

Importing script modules

Importing Workflows, Custom Tasks, Script Modules, and Activities

Adding Script Modules

To create a new script module, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Modules tab.

Step 3

Click Add.

Step 4

In the Modules Information screen, complete the following:

Name

Description

Module Name field

The name for the script module.

Module Description field (optional but recommended)

A description of the script module.

Step 5

Click Submit.

Adding Libraries

To add a task library, do the following:

Before You Begin

A script module is required before you can add a library. See Adding Script Modules

Step 1

On the menu bar, choose Policies > Orchestration..

Step 2

Click the Script Modules tab.

Step 3

In the Script Modules pane, double-click the script module to which you want to add the library.

Step 4

Click the Library tab.

Step 5

Click Add.

Step 6

In the Library Information screen, complete the following:

Name

Description

Name field

The name for the script module.

Description field

The description for the script module.

Script text box

Add library scripts in this area.

Step 7

Click Submit.

- Accessing Libraries

Accessing Libraries

You can access libraries in the followings ways:

Invoke a Library from Another Library

Use the following syntax to invoke a library from another library:loadLibrary("Module Name>/<Library Name>")

For example:

ImportPackage(java.lang);

function test1(){
logger.addInfo("test1");
loadLibrary("Test_Module/testlib1");
}
test1();

Invoke a Library from a Custom Task

When you create a custom workflow task, you can use the syntax shown in this example to invoke a library. Refer to the Cisco UCS Director Custom Task Getting Started Guide for more information on using custom tasks, including how to invoke a library from a custom task.

Jar Files

You can register .jar files with a script module. Using the script module, you can then invoke the contents of the .jar file (its classes, methods, and resources) from a library or a custom task.

- Adding Jar Files

Adding Jar Files

To add a .jar file to a script module, do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Modules tab.

Step 3

In the Script Modules pane, double-click the script module to which you want to add the jar files.

Step 4

Click the Jars tab.

Step 5

Click Add.

Step 6

In the Add Jar screen, click Browse.

Step 7

Select the .jar file to upload from your local folder.

Step 8

Click Submit.

Lists of Values

A list of values (LOV) is a searchable list that is callable from the Cisco UCS Director GUI or as a task or workflow input. For example, when you choose a data type for a task or workflow input, the choices are presented in an LOV.

You can create an LOV to provide your own set of values for a task or workflow input, and store the LOV in a script module.

- Adding a List of Values

- Editing a List of Values

- Deleting a List of Values

Adding a List of Values

To create a list of values (LOV), do the following.

Before You Begin

Create a Script Module.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module you want to use.

Step 4

Click the LOVs tab.

Step 5

Click Add.

Step 6

In the LOV Information dialog box, complete the following:

Name

Description

Name field

The name of the LOV.

Description field

A description of the LOV (optional).

Script text box

Contains the template code for the LOV provider registration. Provide your own implementation by modifying the getDataProvider() method as described in the next step.

Note:
Edit only the script lines described in the following steps. Do not edit the createLOV(), registerLOV(), or registerGlobalInputs() methods. Doing so could cause the LOV to fail to work.

Step 7

In the Script text box, add name-value pairs to your list as follows:

1. Locate the getDataProvider() function. The function appears as follows:

function getDataProvider(){
var lovRegistry = LOVProviderRegistry.getInstance();
var lovProvider = new com.cloupia.service.cIM.inframgr.forms.wizard.LOVProviderIf({
getLOVs : function(session) {
//provide your own implementation for Lovprovider
var formlovs = [];
var formlov = new FormLOVPair("Flex","1");
formlovs[0] = formlov;
var formlov = new FormLOVPair("Generic","2");
formlovs[1] = formlov;
return formlovs;
//End of implementation for Lovprovider
}
});
return lovProvider;
}

2. Modify the highlighted text to define your own name-value pairs.

Step 8

Click Submit.

Editing a List of Values

To edit an existing list of values (LOV), do the following:

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module that contains the LOV you want to edit.

Step 4

Choose the LOVs tab.

Step 5

Choose the LOV you want to edit.

Step 6

Click Edit.

Step 7

Edit the LOV fields that you are allowed to change.

Name

Description

Name field

Displays the name of the LOV.

Note:
You cannot change the name of an existing LOV.

Description field

A description of the LOV.

Script text box

Edit the template code for the LOV provider registration. Provide your own implementation by modifying the getDataProvider() method as described in Adding a List of Values.

Note:
Do not edit the createLOV(), registerLOV(), or registerGlobalInputs() methods. Doing so could cause the LOV to fail to work.

Step 8

Click Submit.

Deleting a List of Values

Before You Begin

Remove references to this list of values (LOV) from all custom tasks and workflows.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module that contains the LOV you want to delete.

Step 4

Click the LOVs tab.

Step 5

Choose the LOV you want to delete.

Step 6

Click Delete.

Step 7

Click Submit.

Tabular Reports

A tabular report is a columnar list that is callable from the Cisco UCS Director GUI or as a task or workflow input. For example, when you choose a workflow in the Workflow tab, the choices are presented in tabular report.

You can create a tabular report to provide your own predefined set of values for a task or workflow input. You can store the tabular report in a script module.

- Adding a Tabular Report

- Editing a Tabular Report

- Deleting a Tabular Report

Adding a Tabular Report

Before You Begin

Create a Script Module.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module you want to use.

Step 4

Click the Tabular Reports tab.

Step 5

Click the Add (+) button.

Step 6

In the Tabular Report Information dialog box, complete the following:

Name

Description

Tabular Report Name field

The name of the tabular report.

Description field

A description of the LOV (optional).

Column Entries list

Click + (Add) and complete the following fields:

Column Name text box

The name of the column.

Column Type drop-down list

The data type of the column entries. The options are:

- Text

- Integer

- Long

- Double

Column Entries check box

Choose a check box to add an option to a column. The options are:

- Management column check box—Must be checked for exactly one column entry.

- Display column check box—Must be checked for exactly one column entry.

- Hide the Field check box—Check this option for any column entry.

Step 7

Click Submit.

Step 8

Repeat the previous two steps for every column you want to create.

Step 9

Show Script check box—Check this check box to see and edit the Script text area.
The column-creation script in the Script text area is automatically generated when you create columns.

A record consists of a row with one value for each column. Edit the Script text area to create records.

Note:
Do not edit or delete anything before //START OF YOUR IMPLEMENTATION and after //END OF YOUR IMPLEMENTATION in the Script text area.

1. Create Record Entries:
Create a value for each Column Entry defined in the Tabular Report. Create these values in the section of the script between the lines //START OF YOUR IMPLEMENTATION. and //END OF YOUR IMPLEMENTATION.. Use the correct function depending on the Column Type of the Column Entry, as shown in the following list.

- Text—model.addTextValue("value");

- Integer—model.addNumberValue(42);

- Long—model.addLongNumberValue(1000);

- Double—model.addDoubleValue(8.6);

Separate the Record Entry function calls using model.completedRow();.

Step 10

Click Submit.

Example: Creating Record Entries for Column Entries

Suppose that you created two Column Entries for your tabular report. The first column entry has a column name of Name and column type of Text. The second column entry has a column name of Department and a column type of Long. Once you create the column entries in your tabular report, the system generates function calls in the script to create these columns, as follows:

function implementationForTabularReport(report)
{
var model = new TabularReportInternalModel();
model.addTextColumn("Name","Name");
model.addNumberColumn("Department","Department");
model.completedHeader();
//START OF YOUR IMPLEMENTATION.

//END OF YOUR IMPLEMENTATION.
model.updateReport(report);
}
function getSelectionColumnId(){
return "1";
}
function getDisplayColumnId(){
return "0";
}

A section in the middle of the script begins with //START OF YOUR IMPLEMENTATION. and ends with //END OF YOUR IMPLEMENTATION. Create record entries between these two lines. Record entries assign values to the column entries.

The following example assigns a text value of "Smith" to the column with column name Name and a long number value of 40 to the column with column name Department. The function call model.completedRow(); indicates the end of this record entry.

function implementationForTabularReport(report)
{
var model = new TabularReportInternalModel();
model.addTextColumn("Name","Name");
model.addLongNumberColumn("Department","Department");
model.completedHeader();
//START OF YOUR IMPLEMENTATION.

model.addTextValue("Smith");
model.addLongNumberValue(40);
model.completedRow();

//END OF YOUR IMPLEMENTATION.
model.updateReport(report);
}
function getSelectionColumnId(){
return "1";
}
function getDisplayColumnId(){
return "0";
}

Editing a Tabular Report

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module for which you want to edit a tabular report.

Step 4

Choose the Tabular Report tab.

Step 5

Choose the name of the tabular report you want to edit and click Edit.

Step 6

In the Edit dialog box, edit the fields you want to change.

Note:
You can change the Column Type drop-down list values of a Management column or of a Display column. To uncheck the Column Type check box for a Management column or for a Display column, delete the existing Column Entry and create a new one.

Step 7

Click Submit.

Deleting a Tabular Report

Before You Begin

Remove references to the tabular report from all custom workflow tasks.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module that contains the tabular report you want to delete.

Step 4

Choose the Tabular Report tab.

Step 5

Select the name of the tabular report you want to delete.

Step 6

Click Delete.

Step 7

Click Submit.

Context Mapping

A context workflow mapping consists of an action label mapped to a workflow on a page, such that clicking on the action label triggers the workflow.

Note

Strictly speaking, context mapping is not part of orchestration—It's a modification to the Cisco UCS Director user interface (UI). It is included here because it is a useful application of script modules.

The Context Mapping module allows you to dynamically add a context workflow mapping. In this way, you can customize the Cisco UCS Director UI by creating an action label for a page and assigning a workflow to that action label.

Creating a context mapping requires knowing the name of the page to which you are adding the action label. The name, and other metadata, of a page are displayed in an Information dialog that is available when you enable the Developer Menu in Cisco UCS Director.

Enable metadata as described in the next section before you begin to create a context mapping.

- Enabling Metadata

- Adding a Context Mapping

- Editing a Context Mapping

- Deleting a Context Mapping

Enabling Metadata

To access report metadata, first enable the Developer Menu.

Note

The term report in Report Metadata refers to a page in the Cisco UCS Director user interface.

To enable the Developer Menu, do the following:

Step 1

In Cisco IMC Supervisor, click your login name in the upper right.
For example, if you log in as admin, Cisco IMC Supervisor displays admin in the upper right.

Step 2

In the User Information dialog box, click the Advanced tab.

Step 3

Check the Enable Developer Menu (for this session) check box.
The REST API Browser is activated in the Orchestration menu during the current session, and the Report Metadata option becomes available in the report views opened in the session.

Tip:
The Advanced tab also displays the REST API Access Key code for the account.

Step 4

Close the User Information dialog box.

What to Do Next

View report metadata, including the report name, by clicking the Report Metadata action in any report.

Adding a Context Mapping

Before You Begin

- Create a Script Module.

- Identify the page which is to use the action label. Use the report metadata to find the name of this page; see Enabling Metadata. You use this page name when you create a Context Mapping.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module you want to use.

Step 4

Click the Context Mapping tab.

Step 5

Click Add.

Step 6

In the Add Context Mapper dialog box, complete the following:

Name

Description

Name text field

Enter a unique name for the context mapping. The system creates a context workflow mapping that has the same name.

Report Name text field

Enter the name of the report (page) to which to add the action label. This name is the reportName field from the Report Metadata of the report.

Select Tabular Field drop-down list

Click Select to display the Select dialog box. Check the box next to the tabular field you want to use.

Description text field

A description of the context mapping.

Script text area

The script that creates the context workflow mapping and associates it with an existing report.

Note:
The system updates the script with the information you enter in the fields. You do not need to edit the script.

Step 7

Click Submit. The Status column displays Success or Fail.

Step 8

If the result was Fail, edit the Context Mapping to ensure that the correct Report Name and Tabular Field have been entered, then click Submit again.

Step 9

If the result was Success, then, from the menu bar, choose Policies > Orchestration.

Step 10

Click the Context Workflow Mapping tab. The Context Mapping you created is listed in the Mapping Name column.

Step 11

Click the context workflow mapping you created.

Step 12

Click Edit.

Step 13

In the Edit Workflow Mappings dialog box, click Add Workflow.

Step 14

In the Workflow 1 dialog box, complete the following:

Name

Description

Selection Required check box

If you check this box, the Workflow drop-down list no longer has any values available. To make the workflow visible in the workflow drop-down list, execute the Context Workflow Mapping in the Workflow Designer dialog box.

If you do not check this box, provide information for the remaining fields.

Report Name text field

Enter the name of the report (page) to add the action label to. This name is the reportName field from the Report Metadata of the report.

Action Label text field

Enter the name of the action label to connect to the workflow. Must be a unique name.

Workflowdrop-down list

Select the workflow to be executed when the user clicks the action label in the report.

If you checked the Selection Required check box, a new workflow is created. If you did not check the Selection Required check box, choose a workflow listed in this drop-down list.

Selection Required check box

The script that creates the context workflow mapping and associates it with an existing report.

Note:
The system updates the script with the information you enter in the fields. You do not need to edit the script.

Authorized User Types dialog box

Authorized User Types dialog box—In the Select Items dialog box, click the check box for each of the user types you authorize. Your choices are:

- Service End-User

- Group Admin

- System Admin

- Operator/Other Administrator

To add an additional Workflow step to this Context Workflow Mapping, click the Add Workflow button and complete the fields.

To delete a Workflow step from this Context Workflow Mapping, click Delete Field below the workflow you want to delete.

Step 15

If you are satisfied with your workflow mappings, click Submit. In the mapped report, the Action Label that you defined appears.

Editing a Context Mapping

To edit a context mapping, do the following:

Step 1

On the menu bar, choose Policies > Orchestration

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module containing the context mapping you want to edit.

Step 4

Select the Context Mapping tab.

Step 5

Select the name of the context mapping you want to edit and click Edit.

Step 6

In the Edit Context Mapper screen, edit the fields you want to change.
You cannot edit the Name field.

Select a value for the Tabular Fields field. This selection is required; the previous value does not persist.

Step 7

Click Submit.

Deleting a Context Mapping

To delete a context mapping, use the following procedure.

Before You Begin

Remove references to the Context Mapping from all Workflows and reports.

Step 1

On the menu bar, choose Policies > Orchestration.

Step 2

Click the Script Module tab.

Step 3

In the Script Module pane, double-click the script module that contains the context mapping you want to delete.

Step 4

Choose the Context Mapping tab.

Step 5

Choose the name of the context mapping you want to delete.

Step 6

Click Delete. A popup appears to confirm the deletion.

Step 7

Click Submit.

Importing and Exporting Script Modules

You can import and export script modules using the Import and Export actions you use to import and export workflows, custom tasks, and activities.

To import a script module, see Importing Workflows, Custom Tasks, Script Modules, and Activities.

To export a script module, see Exporting Workflows, Custom Tasks, Script Modules, and Activities.

Preface

- Audience

- Conventions

- Related Documentation

- Documentation Feedback

- Obtaining Documentation and Submitting a Service Request

Audience

This guide is intended primarily for data center administrators who use Cisco UCS Director and who have responsibilities and expertise in one or more of the following:

- Server administration

- Storage administration

- Network administration

- Network security

- Virtualization and virtual machines

Conventions

Text Type

Indication

GUI elements

GUI elements such as tab titles, area names, and field labels appear in this font.

Main titles such as window, dialog box, and wizard titles appear in this font.

Document titles

Document titles appear in this font.

TUI elements

In a Text-based User Interface, text the system displays appears in this font.

System output

Terminal sessions and information that the system displays appear in this font.

CLI commands

CLI command keywords appear in this font.

Variables in a CLI command appear in this font.

[ ]

Elements in square brackets are optional.

{x | y | z}

Required alternative keywords are grouped in braces and separated by vertical bars.

[x | y | z]

Optional alternative keywords are grouped in brackets and separated by vertical bars.

string

A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

< >

Nonprinting characters such as passwords are in angle brackets.

[ ]

Default responses to system prompts are in square brackets.

!, #

An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

Note

Means reader take note. Notes contain helpful suggestions or references to material not covered in the document.

Caution

Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Tip

Means the following information will help you solve a problem. The tips information might not be troubleshooting or even an action, but could be useful information, similar to a Timesaver.

Timesaver

Means the described action saves time. You can save time by performing the action described in the paragraph.

Warning

IMPORTANT SAFETY INSTRUCTIONS

This warning symbol means danger. You are in a situation that could cause bodily injury. Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with standard practices for preventing accidents. Use the statement number provided at the end of each warning to locate its translation in the translated safety warnings that accompanied this device.

SAVE THESE INSTRUCTIONS

Related Documentation

Cisco UCS Director Documentation Roadmap

For a complete list of Cisco UCS Director documentation, see the Cisco UCS Director Documentation Roadmap available at the following URL: Click Here .

Cisco UCS Documentation Roadmaps

For a complete list of all B-Series documentation, see the Cisco UCS B-Series Servers Documentation Roadmap available at the following URL: Click Here .

For a complete list of all C-Series documentation, see the Cisco UCS C-Series Servers Documentation Roadmap available at the following URL: Click Here .

Note

The Cisco UCS B-Series Servers Documentation Roadmap includes links to documentation for Cisco UCS Manager and Cisco UCS Central. The Cisco UCS C-Series Servers Documentation Roadmap includes links to documentation for Cisco Integrated Management Controller.

Documentation Feedback

To provide technical feedback on this document, or to report an error or omission, please send your comments to ucs-director-docfeedback@cisco.com. We appreciate your feedback.

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What's New in Cisco Product Documentation.

To receive new and revised Cisco technical content directly to your desktop, you can subscribe to the What's New in Cisco Product Documentation RSS feed. RSS feeds are a free service.

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Click Here . Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)