Cisco Active Network Abstraction Workflow User Guide Version 3.5.2 - Working with the Cisco ANA Workflow Editor [Cisco Active Network Abstraction]

Table Of Contents

Working With the Cisco ANA Workflow Editor

Starting Cisco ANA Workflow Editor

Cisco ANA Workflow Editor Window

Creating a New Workflow Template

Workflow Template Names

Retrieving a Workflow Template

Deploying a Workflow Template

Deleting a Workflow Template

Viewing Workflow Properties

Working With the Task Library

Execute BQL Task

Workflow Call Task

Subflow Task

Lock Task

Unlock Task

Testing a Workflow

Gateway Workflow Commands and Operations

Deleting a Template

Running a Workflow

Aborting a Workflow

Deleting a Workflow

Getting Workflow Output

Logging Out

Working With the Cisco ANA Workflow Editor

This chapter provides instructions for launching the Cisco ANA Workflow Editor application. In addition, it describes the Cisco ANA Workflow Editor working environment and how to operate the customized functionality.

•Starting Cisco ANA Workflow Editor—Describes how to login to the Workflow Editor.

•Cisco ANA Workflow Editor Window—Briefly describes the Workflow Editor window and the additional customized functions.

•Creating a New Workflow Template—Provides a brief overview of the workflow template creation process.

•Retrieving a Workflow Template—Describes how to retrieve a workflow template that was previously created from the local server.

•Deploying a Workflow Template—Describes how to deploy a workflow template to the server.

•Deleting a Workflow Template—Describes how to delete a workflow template from the local server.

•Viewing Workflow Properties—Describes how to view the properties of a BQL workflow.

•Working With the Task Library—Describes how to view the properties of a BQL, Workflow Call, Subflow, Lock and Unlock tasks.

•Testing a Workflow—Describes how to execute a workflow template on the local server.

•Gateway Workflow Commands and Operations—Describes how to add utility functions using BQL commands.

•Logging Out—Describes how to logout of the Workflow Editor.

Starting Cisco ANA Workflow Editor

This section provides instructions for launching the Workflow Editor. The Workflow Editor is password protected to ensure security. Before you start using the Workflow Editor make sure you know your username, password, and the gateway IP address or hostname. Installation of the Workflow Editor is optional. The Workflow Editor can be installed using the regular client installation package. For more information, refer to Cisco Active Network Abstraction Client Installation Guide. When the client opens it will negotiate with the server in order to validate the license. If the license is not validated the Workflow Editor will not open.

To start the Workflow Editor:

Step 1 From the Start menu, choose the Programs folder, then Cisco ANA > Workflow Editor. The Workflow Editor Login dialog box is displayed.

Step 2 Enter your username and password.

Step 3 Enter the gateway information in the host field as an IP address or hostname,

or

Choose a gateway from the host dropdown list.

Note The gateway IP address or hostname that was used when you last logged in is automatically displayed at the top of the host list.

Step 4 Click OK. The Workflow Editor window is displayed. For more information, see Figure 2-1

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

Cisco ANA Workflow Editor Window

The Workflow Editor window with a template is displayed.

Figure 2-1 Workflow Editor Window

1

Drawing area

2

Task toolbar

3

Task attribute table

4

Tree

5

Action toolbar

The Workflow Editor window displays information on the workflow and the tasks within the workflow.

The following actions are available from the Workflow Editor toolbar and from the Tools menu:

Button

Function

Retrieves (loads) a workflow from the gateway.

Deletes a workflow from the gateway.

Deploys (uploads) the workflow on the gateway.

In addition, the following tasks are available on the toolbar:

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

The Lock task is used to obtain a lock on a resource.

The Unlock task is used to unlock a resource.

The Workflow Call task is used to synchronically execute or call another workflow.

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

Creating a New Workflow Template

The workflow template creation process begins by creating a new workflow template with a unique name. A blank template is created, and opened for editing. The user then adds tasks to the template in order to create the logical flow that is required. The workflow template is stored locally, and each update is automatically saved.

Workflow Template Names

When you create the unique name for each workflow template, do not include the following wildcard characters:

•"_" denotes any single character

•"%" denotes a zero or many characters

If the "_" and "%" characters are included in the workflow template, you will see the following message in the AVM66 log when you try to run the template or reference it in a subflow:
"WARN [13 21:00:08,248] - dralasoft.workflow - Task aborted. Task: 245886, Workflow: 
245885 java.lang.IllegalArgumentException: Template AA_BB.template is ambiguous, templates 
ids are: 245874 , 245873"
The following examples show workflow template names that can lead to ambiguity if they are deployed together:

•WFTLM_MUESTRA.template and WFTLM#MUESTRA.template

•WFTLM%MUESTRA.template and WFTLM####MUESTRA.template

The ambiguity only occurs when the template containing the wildcard characters is run.

Retrieving a Workflow Template

The user can retrieve a workflow template that was previously created and deployed on the gateway or server. Once the workflow template has been retrieved, the user 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 On the toolbar, click Retrieve Workflow. The Retrieve Workflow template from the Server dialog box is displayed.

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

Step 2 Choose the 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 the user has tested the workflow template locally and is satisfied, the workflow template can be deployed to the Cisco ANA server (remote server), where it will be available to all authorized users.

To deploy a workflow template:

Step 1 On 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 will ask if you want to replace the existing workflow.

Step 3 Click OK. The selected workflow template is deployed.

Deleting a Workflow Template

The user 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 On the toolbar, click Delete Workflow from Server. The Delete Workflow Template from Server dialog box is displayed.

Step 2 Choose 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 enables the user to view the workflow callback scripts. The user can view the properties of a BQL 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 2-2 Workflow Properties Dialog Box - General Properties Tab

Step 3 Choose the Attributes tab. The attributes of the BQL workflow are displayed.

Figure 2-3 Attributes Tab

Step 4 Choose the Callback Scripts tab.

Figure 2-4 Callback Scripts Tab

The Select Script list enables the user to choose one of the following options in order to activate the script:

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

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

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

•exceptionScript—Activates 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 BQL Task

•Workflow Call Task

•Subflow Task

•Lock Task

•Unlock Task

Execute BQL Task

To view the properties of an Execute BQL task:

Step 1 Create or retrieve the required workflow template.

Step 2 Choose the required BQL 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 2-5 Task Properties Dialog Box - General Properties Tab

Note The Earliest Start option is not supported.

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

Figure 2-6 Attributes Tab

Step 5 Choose the Command Template tab.

Figure 2-7 Command Template Tab

Use the Command Template tab to enter the command template XML to create a command instance descriptor (CID) used for running the gateway command or activation script.

The format of the template is similar to a CID, with the option for setting parameters that would be evaluated on execution:

•$Attribute name$—Will be evaluated by that name from a workflow attribute.

•$Task name:Attribute name$—Will be evaluated by that name by a task attribute.

If an invalid attribute or task name is entered, the evaluation of the command template will fail and stop the task. The following error message is displayed:
Failed to create command, task [Task] not performed, aborting task.
Reason: Attribute <Attribute name> evaluation failed, aborting command creation
Note Each BQL task includes a task attribute called RollbackEnabled. This attribute defines whether or not this BQL task command will be rolled back if the workflow stops. The default value is True.

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

Workflow Call Task

The Workflow Call task is used to synchronically run or call another workflow, which will be recognized as a child of this workflow.

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

To view the properties of a Workflow Call task:

Step 1 Create or retrieve the required workflow template.

Step 2 Choose 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 2-8 Task Properties Dialog Box - Assign Attributes Tab

The Assign Attributes tab enables the user to 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

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

Figure 2-9 General Properties Tab

Note The Earliest Start option is not supported.

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

Step 6 Choose the Target Template tab.

Figure 2-10 Target Template Tab

The Target Template tab enables the user to choose the workflow template that will be 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 run 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 Choose 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 2-11 General Properties Tab - Subflow

Note The Earliest Start option is not supported.

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

Step 5 Choose the Target Template tab.

Figure 2-12 Target Template Tab - Subflow

The Target Template tab enables the user to choose the workflow template that will be 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 Choose 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 2-13 General Properties Tab - Lock

Note The Earliest Start option is not supported.

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

Step 5 Choose the Resource Names tab.

Figure 2-14 Resource Names Tab - Lock

The Resource Names tab enables the user to specify the resources that should be locked.

Note It is also possible to lock multiple resources.

In the text area, enter the resources names to be locked. Each resource name should be on a separate line.

Resource names can be passed as parameters, that will be resolved during task execution to either workflow or task attributes:

•$Attribute name$—Will be evaluated from a workflow attribute by that name.

•$Task name:Attribute name$—Will be evaluated by a task attribute by that name.

The result of the lock task is stored in an attribute named Result in the lock task as follows:

•Success - lock successfully obtained.

or

•Failed due to timeout - lock failed due to timeout

or

•Failed due to deadlock - lock failed due to a deadlock
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 Choose 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 2-15 General Properties Tab - Unlock

Note The Earliest Start option is not supported.

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

Step 5 Choose the Resource Names tab.

Figure 2-16 Resource Names Tab - Unlock

The Resource Names tab enables the user to specify the resources that should be unlocked. In the text area, enter the resources names to be unlocked. Each resource name should be on a separate line.

Resource names can be passed as parameters, that will be resolved during task execution to either workflow or task attributes:

•$Attribute name$—Will be evaluated from a workflow attribute by that name.

•$Task name:Attribute name$—Will be evaluated by a task attribute by that name.

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

Testing a Workflow

The user can test a BQL workflow locally on the client. This section describes testing a workflow that includes a BQL task.

To test a BQL 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 On the toolbar, click Execute Workflow. The Workflow Editor window changes and displays an additional set of views, as shown in the example.

Figure 2-17 Execute Workflow

The new tab that is created in the upper row and displayed in the Workflow Editor window reflects the activation status. For more information about activation status, see "Introducing the Cisco ANA Workflow Editor".

In addition, the following views are displayed in the window and relate to the activation of the workflow:

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

•Tabular View—Displays a table of all 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 Activation is clicked. Click Abort to stop the workflow.

•Copy—Copies the workflow.

•Delete—Deletes a running workflow.

Step 3 Click Activate. The Console window is displayed.

Figure 2-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 colors (in the bottom right corner), as shown in the example.

Figure 2-19 Tasks Displayed In the Graphical View Tab

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

•Blue—Ready

•Green—Active

•Red—Abort

•Grey—Done

•Light Grey—Passive

For more information about activation status, see "Introducing the Cisco ANA Workflow Editor".

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

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

Gateway Workflow Commands and Operations

This section describes how to add utility functions using BQL commands.

Deleting a Template

To delete a template from the server, use the following BQL command:
<?xml version="1.0" encoding="UTF-8"?>
<command name="Delete">
<param name="oid">
<value>{[WorkflowTemplate(Name=template-name)]}</value>
</param>
</command>
Running a Workflow

To execute a workflow based on an installed template, use the following BQL command:
<?xml version="1.0" encoding="UTF-8"?>
<command name="RunWorkflow">
<param name="templateOid">
<value>{[WorkflowTemplate(Name=template-name)]}</value>
</param>
<param name="workflowAttributes">
<value>
    <IWorkflowAttribute>
        <ID type="Oid">{[WorkflowAttribute(Name=attribute1-name)]}</ID>
        <Value type="String">attribute1-value</Value>
    </IWorkflowAttribute>
    <IWorkflowAttribute>
        <ID type="Oid">{[WorkflowAttribute(Name=attribute2-name)]}</ID>
        <Value type="String">attribute2-value</Value>
    </IWorkflowAttribute>
...and so on for other attributes...
</value>
<IMObject_Array/>
</param>
</command>
This command returns the OID of the new workflow. For example:
------ com.sheer.framework.imo.Oid ------ 
{[Workflow(Id=801)]} 
-----------------------------------------
Aborting a Workflow

To abort a workflow, which includes, stopping it if it is running and rolling back all the activation scripts that it has executed, use the following BQL command:
<?xml version="1.0" encoding="UTF-8"?>
<command name="AbortWorkflow">
<param name="oid">
<value>{[Workflow(Id=workflow-id)]}</value>
</param>
</command>
If successful, this command returns nothing.

Deleting a Workflow

To delete a workflow that is not active, namely, one that has already been completed or was aborted, use the following BQL command:
<?xml version="1.0" encoding="UTF-8"?>
<command name="Delete">
<param name="oid">
<value>{[Workflow(Id=workflow-id)]}</value>
</param>
</command>
If successful, this command returns nothing.

Getting Workflow Output

To get the output of a workflow, both during its testing and afterwards, use the following BQL command:
<?xml version="1.0" encoding="UTF-8"?>
<command name="GetWorkflowOutput">
<param name="oid">
<value>{[Workflow(Id=workflow-id)]}</value>
</param>
</command>
This command returns the output as a string. For example:
<?xml version="1.0" encoding="UTF-8"?>
<IMO>
<Output type="String">
...
progress messages and script testing results
...
</Output>
</IMO>
Logging Out

When you have finished working with the Workflow Editor you can log out of the application. Any open workflow templates are automatically saved when you log out.

To log out of the Cisco ANA Workflow Editor:

Step 1 From the File menu, choose Exit,

or

Click in the top right-hand corner to close the Workflow Editor window.

The Workflow Editor is closed.