Appendix B: Using the Workflow Editor to Create Task Workflows

Table Of Contents

Using the Workflow Editor to Create Task Workflows

Workflow Task Types and Activation States

Workflow Overview: Step-by-Step

Working with the Workflow Editor

Creating a New Workflow Template

Retrieving a Workflow Template

Deploying a Workflow Template

Deleting a Workflow Template

Viewing Workflow Properties

Working with the Task Library

Executing (Testing) a Workflow Locally

Running a Workflow on the Gateway

Extending the Workflow Engine with Custom Tasks and Workflow Editor Callbacks

Using the Workflow Editor to Create Task Workflows

A workflow consists of several tasks grouped together and arranged in a hierarchy. These workflows run gateway commands and provide complete access to ANA's live network information model. Relationships between tasks in a workflow can include sequences, branches, failure procedures, and access to ANA commands, as well as ANA's information model.

The Workflow Editor provides a user interface that helps you create complex flows with a minimum of effort, to match the activation needs of your network. After creating your workflows, you can run them locally within the editor to validate them before executing them on network elements.

Note The ANA online help, which is launched from the ANA main toolbar by choosing Help > Help Contents, explains the enhancements that were made to the Workflow Editor for ANA. The ANA Workflow Editor online help also provides some clarifications of the vendor-provided functions. However, the vendor online help describes some features that are no longer part of the Workflow Editor that is packaged with ANA, so you should ignore those descriptions in the vendor online help.

The workflow engine is a processing module that provides services for executing workflows and for storing workflow templates (definitions). The engine resides on the gateway, using AVM 66. After a workflow is deployed (a template is created and stored), it is accessible for viewing properties and status. In addition, you can view a history of the invoked workflows using the Troubleshooting perspective.

See these topics for more specific information on workflows:

• Workflow Task Types and Activation States

• Workflow Overview: Step-by-Step

• Working with the Workflow Editor

• Extending the Workflow Engine with Custom Tasks and Workflow Editor Callbacks

Workflow Task Types and Activation States

Each workflow task performs a specific function and can be quickly added and configured using the Workflow Editor. Tasks can be classed as predecessor or successor tasks. As the names imply, a predecessor task must be completed before the next task can be executed, and a successor task is executed after a predecessor task. Each task has an associated activation state:

•Ready—The task is ready to begin when the constraints (for example, start time or predecessors) have been satisfied.

•Active—The task is being executed.

•Done—The task is complete.

•Abort—The task has failed or the state has been set manually. The task can be manually reset to Ready or Done.

•Passive—The task exists, but is no longer relevant. For the purposes of successive tasks, the passive task is considered done.

The workflow below shows a typical task sequence:

Figure B-1 Typical Task Sequence

Execute Task

The Execute Task is located in the task toolbar of the Workflow Editor. This task executes the Command Builder command specified in the Command Template tab of the Task Properties dialog box, and stores the result in a Task attribute called Result so that it can be used by scripts and other tasks.

The Command Template tab can reference workflow attributes and task attributes. At runtime, the attribute's values are substituted into the template before it is executed.

Lock/Unlock Task

The Lock task has two main objectives, namely:

•To allow workflow instances to declare the resources that they use and the scope of their usage.

•To ensure that those resources are not used by any other workflow instance during that scope.

The Lock task allows you to protect any component from concurrent use by multiple workflows. You can lock an object that represents a single resource and guard the access to it. A resource's identifier serves as the name of the lock. At any given time, a lock can only be owned by one workflow. Resources can be automatically locked during rollback.

The system prevents deadlocks before they occur. Upon detecting an imminent deadlock, the lock operation belonging to the workflow with the least progress fails. A failed lock may or may not abort the workflow.

The locking mechanism does not cover every access to every resource. Only workflows participate in the locking process. Non-workflow activities may access a resource even when it is locked by a workflow. Participation in the locking process is optional.

You can:

•Lock or unlock single or multiple resources.

•Unlock resources when a workflow terminates.

•Lock resources during rollback.

Workflow Call (Synchronous Workflow Nesting)

Synchronous workflow nesting allows workflow designers to invoke subworkflows synchronously, and pass arguments to each sub-workflow invocation. This enables the workflow designer to isolate the tasks executing in the sub-workflow as much as possible from the tasks executing in the parent workflow and in other sub-workflows.

The following functionality is available:

•The child workflow is executed in a separate workflow. The parent workflow waits for the child workflow to terminate.

•When a child workflow is aborted, it causes its parent workflow to also abort.

•The child workflow has a separate scope for attributes.

•The output of the child workflow is directed to the parent workflow.

•The parent workflow can pass parameters to its child workflow.

•The correct rollback sequence is maintained throughout the depth of the lineage.

•The child workflows are not visible through the API. The user interacts directly with the parent.

•Delete and abort operations on parent workflows are delegated to child workflows.

Note The maximum workflow nesting depth is 16.

Workflow Overview: Step-by-Step

These steps describe how to create and manage your workflows.

Table B-1 Create and Manage Workflows

To Perform this Task...

See...

Step 1

Create a command using Command Builder and preview it.

Managing and Deploying Configuration Changes, page 8-1

Step 2

Define tasks and workflows:

a. Copy the Command Builder scripts to the command template tabs for the Workflow Editor Execute Tasks

b. Edit the Command Builder scripts, if required.

c. Add workflow and task attributes.

Creating a New Workflow Template

Step 3

Test the workflow locally.

Executing (Testing) a Workflow Locally

Step 4

Deploy the workflow on the gateway.

Deploying a Workflow Template

Step 5

Run the workflow on the gateway.

Running a Workflow on the Gateway

Step 6

View the results of the workflow.

Running a Workflow on the Gateway

Understanding the Workflow Editor User Interface

Figure B-2 shows the Workflow Editor window with a template. You can open the Workflow Editor by clicking the Workflow icon in the Inventory perspective main toolbar:

Opens the Workflow Editor.

Note The Workflow Editor window appears empty when it is opened. You can create a new workflow and/or retrieve a workflow that was created previously.

Figure B-2 Workflow Editor Window

1

Drawing Area

2

Task Toolbar

3

Task Attribute Table

4

Tree

5

Action Toolbar

The Workflow Editor window contains these actions which have been customized and added to the action toolbar:

Button

Function

Retrieves (loads) a workflow from the gateway.

Deletes a workflow from the gateway.

Deploys (uploads) a workflow to the gateway.

Launches vendor online help.

Note The ANA online help, which is launched from the ANA main toolbar by choosing Help > Help Contents, explains the enhancements that were made to the Workflow Editor for ANA. The ANA Workflow Editor online help also provides some clarifications of the vendor-provided functions. However, the vendor online help describes some features that are no longer part of the Workflow Editor that is packaged with ANA, so you should ignore those descriptions in the vendor online help.

In addition, the following customized tasks have been added to the task toolbar:

Button

Function

Obtains a lock on a resource.

Unlocks a resource.

Synchronically executes/calls another workflow.

Embeds and executes another workflow.

Roles Required to Use the Workflow Editor

Table B-2 lists the roles that are required to use the Workflow Editor. For more information on roles, see Creating and Managing Users and Scopes, page 14-27.

Table B-2 Roles Required to Use the Workflow Editor

Task

Role Required

Create a workflow

All

Open a workflow

All

Close a workflow

All

Save as/Rename a workflow

All

Delete a workflow

All

Execute a workflow

All

Retrieve a workflow from a server

All

Delete a workflow from a server

All

Deploy a workflow

All

Working with the Workflow Editor

These topics provide instructions for launching the Workflow Editor feature. The Workflow Editor window contains these actions which have been customized and added to the action toolbar.

• Creating a New Workflow Template

• Retrieving a Workflow Template

• Deploying a Workflow Template

• Deleting a Workflow Template

• Viewing Workflow Properties

• Working with the Task Library

• Executing (Testing) a Workflow Locally

• Running a Workflow on the Gateway

Creating a New Workflow Template

The workflow template creation process begins when you create a new workflow template with a unique name. A blank template is created, and opened for editing. You then add tasks to the template to create the logical flow that is required. The workflow template is stored locally, and each update you make is automatically saved.

For information about creating new workflows, see the Workflow Editor online help by clicking the Help button in the Action toolbar (see Understanding the Workflow Editor User Interface).

Retrieving a Workflow Template

You can retrieve a workflow template that was previously created and deployed on the gateway or server. Once the workflow template has been retrieved you can do one of the following:

•Edit the workflow template

•Deploy the workflow template

•Execute the workflow template

•Delete the workflow template

To retrieve a workflow template:

Step 1 In the toolbar, click Retrieve Workflow. The Retrieve Workflow Template from Server dialog box is displayed.

The Retrieve Workflow Template from Server dialog box displays the list of existing workflow templates.

Step 2 Select the required workflow template that you want to load from the list.

Step 3 Click OK. A confirmation message is displayed.

Step 4 Click OK. The required workflow template is opened and displayed in the Workflow Editor window.

Deploying a Workflow Template

After you have tested the workflow template locally, you can deploy the workflow template to the gateway, where it is available to all authorized users.

To deploy a workflow template:

Step 1 In the toolbar, click Deploy Workflow. A confirmation message is displayed.

Step 2 Click Yes. A success message is displayed.

Note If the workflow template already exists the server asks you if you want to replace the existing workflow.

Step 3 Click OK. The selected workflow template is deployed to the gateway.

Deleting a Workflow Template

You can delete a workflow template from the server.

Note A workflow template does not have to be open or displayed in the Workflow Editor window before it can be deleted.

To delete a workflow template:

Step 1 In the toolbar, click Delete Workflow from Server. The Delete Workflow Template from Server dialog box is displayed.

Step 2 Select the template that you want to delete from the list.

Step 3 Click OK. A success message is displayed.

Step 4 Click OK. The workflow template is deleted from the local server.

Viewing Workflow Properties

The Workflow Properties dialog box lets you view the workflow callback scripts. You can view the properties of an Execute Task workflow.

To view workflow properties:

Step 1 Create or retrieve the required workflow template.

Step 2 Right-click in the Drawing Area to display the menu, and choose Workflow Properties. The Workflow Properties dialog box for the required workflow template is displayed.

Figure B-3 Workflow Properties Dialog Box - General Properties Tab

For information about the Workflow Properties dialog box, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 3 Click the Attributes tab. The attributes of the Execute Task workflow are displayed.

Figure B-4 Attributes Tab

Step 4 Click the Callback Scripts tab.

Figure B-5 Callback Scripts Tab

The Select Script drop-down list lets you select one of the following options to execute (activate) the script:

•preActiveScript—Executes the script before the workflow is active.

•activeScript—Executes the script when the workflow becomes active.

•doneScript—Executes the script when the workflow is successfully completed.

•exceptionScript—Executes the script if one of the tasks in the workflow fails.

The Execute button runs the script for testing purposes.

Step 5 Click OK. The Workflow Properties dialog box is closed.

Working with the Task Library

This section describes viewing the properties of the following tasks:

• Execute Task

• Workflow Call Task

• Subflow Task

• Lock Task

• Unlock Task

• Notes on Delay and Escalate Tasks

Execute Task

Execute Task is used to invoke commands previously created and residing on the gateway. This is the main task used for implementing an activation workflow.

The command template can include the following parameters:

•$Attribute name$—is Evaluated as a workflow attribute.

•$Task name:Attribute name$—is Evaluated as a task attribute.

To view the properties of an Execute Task:

Step 1 Create or retrieve the required workflow template.

Step 2 Select the required Execute Task in the Drawing Area.

Step 3 Right-click to display the menu, and choose Task Properties. The Task Properties dialog box for the required task is displayed.

Figure B-6 Task Properties Dialog Box - General Properties Tab

Note The Earliest Start option is not supported.

For information about the Task Properties dialog box, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 4 Click the Attributes tab. The attributes of the task are displayed.

Figure B-7 Attributes Tab

Step 5 Click the Command Template tab.

Figure B-8 Command Template Tab

The Command Template tab lets you edit the command template used to create a command descriptor for executing the activation script. In addition, you can paste the XML code here to invoke the command.

Step 6 Click OK. The Task Properties dialog box is closed.

Workflow Call Task

The Workflow Call task is used to synchronically execute/call another workflow, which is recognized as a child of this workflow.

Note The maximum workflow nesting depth is 16.

To view the properties of a Workflow Call task:

Step 1 Create or retrieve the required workflow template.

Step 2 Select the required Workflow Call task in the Drawing Area.

Step 3 Right-click to display the menu, and choose Task Properties. The Task Properties dialog box for the required task is displayed.

Figure B-9 Task Properties Dialog Box - Assign Attributes Tab

The Assign Attributes tab lets you pass parameters as attributes to child workflows.

An attribute can be assigned to a child workflow in two ways:

•By specifying a workflow attribute in a parent workflow, as follows:

attribute_in_child_workflow=attribute_in_parent_workflow

•By specifying a task in a parent workflow followed by a colon (:) and the attribute name, as follows:

attribute_in_child_workflow=task_in_parent_workflow:attribute_name

For information about the Task Properties dialog box, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 4 Click the General Properties tab. The general properties of the task are displayed.

Figure B-10 General Properties Tab

Note The "Earliest Start" option is not supported.

Step 5 Click the Attributes tab. The attributes of the task are displayed.

Step 6 Click the Target Template tab.

Figure B-11 Target Template Tab

The Target Template tab lets you choose the workflow template that is defined as the child workflow.

Step 7 Click OK. The Task Properties dialog box is closed.

Subflow Task

The Subflow task is used to embed and execute another workflow in this workflow instance.

Note The maximum workflow nesting depth is defined in the registry. The default value is 16.

To view the properties of a Subflow task:

Step 1 Create or retrieve the required workflow template.

Step 2 Select the required Subflow task in the Drawing Area.

Step 3 Right-click to display the menu, and choose Task Properties. The Task Properties dialog box for the required task is displayed.

Figure B-12 General Properties Tab - Subflow

Note The "Earliest Start" option is not supported.

For information about the Task Properties dialog box, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 4 Click the Attributes tab. The attributes of the task are displayed.

Step 5 Click the Target Template tab.

Figure B-13 Target Template Tab - Subflow

The Target Template tab lets you select the workflow template that is embedded.

Step 6 Click OK. The Task Properties dialog box is closed.

Lock Task

The Lock task is used to create a lock on specific resources.

To view the properties of a Lock task:

Step 1 Create or retrieve the required workflow template.

Step 2 Select the required Lock task in the Drawing Area.

Step 3 Right-click to display the menu, and choose Task Properties. The Task Properties dialog box for the required task is displayed.

Figure B-14 General Properties Tab - Lock

Note The "Earliest Start" option is not supported.

For information, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 4 Click the Attributes tab. The attributes of the task are displayed.

Step 5 Click the Resource Names tab.

Figure B-15 Resource Names Tab - Lock

The Resource Names tab lets you specify the resources that should be locked.

Note It is possible to lock multiple resources as well.

Step 6 Click OK. The Task Properties dialog box is closed.

Unlock Task

The Unlock task is used to unlock specific locked resources.

To view the properties of an Unlock task:

Step 1 Create or retrieve the required workflow template.

Step 2 Select the required Unlock task in the Drawing Area.

Step 3 Right-click to display the menu, and choose Task Properties. The Task Properties dialog box for the required task is displayed.

Figure B-16 General Properties Tab - Unlock

Note The "Earliest Start" option is not supported.

For information about the Task Properties dialog box, see the Workflow Editor online help by clicking the Help button in the Action toolbar.

Step 4 Click the Attributes tab. The attributes of the task are displayed.

Step 5 Click the Resource Names tab.

Figure B-17 Resource Names Tab - Unlock

The Resource Names tab lets you specify the resources that should be unlocked.

Step 6 Click OK. The Task Properties dialog box is closed.

Notes on Delay and Escalate Tasks

The Delay and Execute tasks both allow you to configure a delay property, which specifies the following:

•For Delay tasks, it specifies a task's sleep time.

•For Escalate tasks, it specifies the amount of time to wait before escalating (starting another task in the workflow).

However, how this affects the workflow depends on whether the workflow engine is configured to use absolute time or a business calendar. If the useCalendar property is set to true, the workflow uses the business calendar, which is configured using the CALENDAR.DWE system property, defined in the engine XML file. See the vendor online help for more information (see Understanding the Workflow Editor User Interface).

Executing (Testing) a Workflow Locally

You can execute (test) an Execute Task workflow locally on the client. For more information about executing a workflow, see the Workflow Editor online help by clicking the Help button in the Action toolbar. This section describes executing (testing) a workflow that includes a Command Builder task.

To execute a workflow:

Step 1 Create a new workflow in the Workflow Editor window (see Creating a New Workflow Template) or retrieve a workflow (see Retrieving a Workflow Template).

Step 2 In the toolbar, click Execute Workflow. The Workflow Editor window changes and displays a new tab near the top of the window, reflecting the activation status (see Workflow Task Types and Activation States). For example, the new tab might say READY.

The following views, which are displayed in the window (lower row), relate to the state of your workflow test on your local machine:

•Graphical View—Displays the workflow as a graphical presentation.

•Tabular View—Displays a table of all of the tasks in the workflow.

•Workflow State Analysis—Displays an analysis of the activation status of the workflow.

•XML View—Displays the XML code of the current workflow.

In addition, the following buttons are displayed at the bottom of the window:

•Activate—Activates the workflow.

Note This button toggles to Abort when Activate is clicked. Clicking Abort aborts the workflow.

•Copy—Copies the workflow.

•Delete—Deletes an executing workflow.

Step 3 Click Activate. The Console window is displayed.

Figure B-18 Console Window

The Console window displays the results of each task in the workflow.

Step 4 Click to close the Console window. The Workflow Editor window is displayed.

The tasks displayed in the Graphical View tab (lower row) display the activation status of each task using an oval shape and various colors (in the bottom right corner), as shown in the example.

Figure B-19 Tasks Displayed In the Graphical View Tab

These colors change as the status of the task changes during the execution process, as follows:

•Blue—Ready

•Green—Active

•Red—Aborted

•Grey—Done

•Light Gray—Inactive

For more information about activation status, see page 2.

Step 5 Review the results of the execution of the workflow in the Workflow Editor window.

Once the workflow has been executed (tested) successfully locally on the client, you can deploy the workflow to the gateway. For more information, see Deploying a Workflow Template.

Running a Workflow on the Gateway

You can use standardized ANA APIs to run workflows on the gateway, and to receive status about those workflows. For information on how to do this, see Cisco Active Network Abstraction Information Model Primer.

Extending the Workflow Engine with Custom Tasks and Workflow Editor Callbacks

You can develop and install custom tasks for your special project needs. For more information, see these sections of the vendor online help:

•Customization > Task and Workflow Property Dialogs

•Engine API > Customizing Engine Behavior

To launch the vendor online help, click the question mark icon, as described in Understanding the Workflow Editor User Interface.

	To Perform this Task...	See...
Step 1	Create a command using Command Builder and preview it.	Managing and Deploying Configuration Changes, page 8-1
Step 2	Define tasks and workflows: a. Copy the Command Builder scripts to the command template tabs for the Workflow Editor Execute Tasks b. Edit the Command Builder scripts, if required. c. Add workflow and task attributes.	Creating a New Workflow Template
Step 3	Test the workflow locally.	Executing (Testing) a Workflow Locally
Step 4	Deploy the workflow on the gateway.	Deploying a Workflow Template
Step 5	Run the workflow on the gateway.	Running a Workflow on the Gateway
Step 6	View the results of the workflow.	Running a Workflow on the Gateway

1	Drawing Area
2	Task Toolbar
3	Task Attribute Table
4	Tree
5	Action Toolbar

Task	Role Required
Create a workflow	All
Open a workflow	All
Close a workflow	All
Save as/Rename a workflow	All
Delete a workflow	All
Execute a workflow	All
Retrieve a workflow from a server	All
Delete a workflow from a server	All
Deploy a workflow	All