Cisco Active Network Abstraction Customization User Guide, 3.6.6 - 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

Workflow Editor Attribute Types

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 Workflow Editor application, describes the Workflow Editor working environment, and explains how to operate the customized functionality.

This chapter includes:

•Starting Cisco ANA Workflow Editor

•Cisco ANA Workflow Editor Window

•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

•Testing a Workflow

•Gateway Workflow Commands and Operations

•Logging Out

Starting Cisco ANA Workflow Editor

This section provides instructions for launching the Workflow Editor. The Workflow Editor is password-protected to ensure security. Before 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, see the Cisco Active Network Abstraction 3.6.6 Installation Guide.

When the client opens, it negotiates with the server to validate the license. If the license is not validated, the Workflow Editor does not open.

To start the Workflow Editor:

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

Step 2 Enter your username and password.

Step 3 Specify the gateway in one of the following ways:

•Enter the gateway information in the Host field as an IP address or hostname.

•Choose a gateway from the Host drop-down list.

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

Step 4 Click OK. The Workflow Editor window is displayed (see Figure 9-1).

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

Cisco ANA Workflow Editor Window

Figure 9-1 shows the Workflow Editor window with a template.

Figure 9-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.

Table 9-1 identifies the icons and actions that are available in the Workflow Editor toolbar and the Tools menu.

Table 9-1 Toolbar and Tool Menu Options

Button

Function

Retrieves (loads) a workflow from the gateway.

Deletes a workflow from the gateway.

Deploys (uploads) the workflow on the gateway.

Table 9-2 identifies additional icons and actions that are available in the toolbar.

Table 9-2 Additional Toolbar Options

Icon

Function

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

Lock is used to obtain a lock on a resource.

Unlock is used to unlock a resource.

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

Subflow is used to embed and execute another workflow.

Creating a New Workflow Template

The workflow template creation process begins with creating 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 is automatically saved.

Workflow Template Names

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

•Underscore ( _ ) to denote a single character.

•Percent (%) to denote a zero or many characters.

If you include _ and % in the workflow template, the following message appears 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.

Workflow Editor Attribute Types

By default, all attributes in Workflow Editor are of the type String. To use another attribute type, such as Integer, set the flag use-workflow-string-param-casting to true in /export/home/sheer4/Main/registry/workflowavm.xml. In workflowavm.xml, the flag use-workflow-string-param-casting appears under the workflow key.

After you change this flag to true, you can use attribute types other than String.

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 On the toolbar, click Retrieve Workflow.

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.

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 and are satisfied with it, you can deploy it to the Cisco ANA server (remote server), where it becomes 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 if you want to replace the existing workflow.

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

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 Choose the template that you want to delete.

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 you to view the workflow callback scripts. You 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 the drawing area to display the menu, then choose Workflow Properties. The Workflow Properties dialog box for the required workflow template is displayed (Figure 9-2).

Figure 9-2 Workflow Properties Dialog Box - General Properties Tab

Step 3 Choose the Attributes tab. The attributes of the BQL workflow are displayed (Figure 9-3).

Figure 9-3 Attributes Tab

Step 4 Choose the Callback Scripts tab (Figure 9-4).

Figure 9-4 Callback Scripts Tab

The Select Script list enables you to choose one of the following options 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 the BQL task, then choose Task Properties. The Task Properties dialog box for the required task is displayed (Figure 9-5).

Figure 9-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 9-6).

Figure 9-6 Attributes Tab

Step 5 Choose the Command Template tab (Figure 9-7).

Figure 9-7 Command Template Tab

Use the Command Template tab to enter the command template XML to create a command instance descriptor (CID) 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$—Is evaluated by that name from a workflow attribute.

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

If an invalid attribute or task name is entered, the evaluation of the command template fails and stops 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 is rolled back if the workflow stops. The default value is True.

Step 6 Click OK. The Task Properties dialog box closes.

Workflow Call Task

The Workflow Call task is used to synchronically run or call another workflow, which is 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 the task, then choose Task Properties. The Task Properties dialog box for the required task is displayed (Figure 9-8).

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

The Assign Attributes tab enables you 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 9-9).

Figure 9-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 9-10).

Figure 9-10 Target Template Tab

The Target Template tab enables you to choose the workflow template that is to 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 a 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 the task, then choose Task Properties. The Task Properties dialog box for the required task is displayed (Figure 9-11).

Figure 9-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 9-12).

Figure 9-12 Target Template Tab - Subflow

The Target Template tab enables you to choose the workflow template that is to 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 the task, then choose Task Properties. The Task Properties dialog box for the required task is displayed (Figure 9-13).

Figure 9-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 9-14).

Figure 9-14 Resource Names Tab - Lock

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

Note It is also possible to lock multiple resources.

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

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

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

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

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

•Success - lock successfully obtained.

•Failed due to timeout - lock failed due to timeout.

•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 the task, then choose Task Properties. The Task Properties dialog box for the required task is displayed (Figure 9-15).

Figure 9-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 9-16).

Figure 9-16 Resource Names Tab - Unlock

Step 6 In the text area, enter the resource names to be unlocked. Enter each resource name on a separate line.

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

•$Attribute name$—Evaluated from a workflow attribute by that name.

•$Task name:Attribute name$—Evaluated by a task attribute by that name.

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

Testing a Workflow

You 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 In the toolbar, click Execute Workflow. The Workflow Editor window changes and displays an additional set of views, as shown in Figure 9-17.

Figure 9-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 What Is a Workflow Task?, page 8-2.

The following views are displayed in the window and relate to workflow activation:

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

•Tabular View—Displays a table of all 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.

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 9-18).

Figure 9-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 Figure 9-19.

Figure 9-19 Tasks Displayed In the Graphical View Tab

The 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 What Is a Workflow Task?, page 8-2.

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

Once you have tested the workflow successfully on the local client, you 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 similarly 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 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 (that is, one that has already been completed or 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 afterward, 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, do one of the following:

•Choose File > Exit.

•Click the top right corner to close the Workflow Editor window.

The Workflow Editor is closed.