Workflow Developers Guide

Published on February 2017 | Categories: Documents | Downloads: 40 | Comments: 0 | Views: 291
of 55
Download PDF   Embed   Report

Comments

Content

򔻐򗗠򙳰
Workflow Developer’s Guide

ii

Workflow Developer’s Guide

Contents
Chapter 1. Preparing to write a workflow 1

Chapter 10. Adding and managing
workflow transitions . . . . . . . . . 31

Chapter 2. Tutorial: Creating a new
workflow . . . . . . . . . . . . . . 5

Adding a new transition to the workflow
Editing transition properties . . . . .
Mapping a command variable . . . .
Removing a transition . . . . . . .

Sample workflow: Cisco Turn Port ON
Workflow development standards . .
Workflow naming conventions . .
Variable naming conventions . . .
Describing transitions and variables

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

6
7
8
8
8

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

31
31
31
31

Chapter 11. Adding and managing
workflow variables and parameters . . 33

Chapter 3. Creating a workflow using a
text editor . . . . . . . . . . . . . . 9

Adding a new variable . .
Mapping a variable . . . .
Removing a variable mapping
Deleting a variable . . . .

Chapter 4. Querying the data center
model . . . . . . . . . . . . . . . 13

Chapter 12. Running workflows . . . . 35

Retrieving data from the dcm . . . . .
Inserting data in the dcm . . . . . . .
Updating data in the dcm . . . . . .
Deleting data from the dcm . . . . . .
Retrieving properties of a dcm object . . .
Inserting properties into the dcm . . . .
Updating the properties of a dcm object . .
Deleting the properties of a dcm object . .
Data center model query language syntax .
Reading dcm query language expressions

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

13
14
15
15
15
16
16
16
17
17

Chapter 5. Conditional and looping
statements . . . . . . . . . . . . . 21
if...then statements . .
if...then...else statements
foreach statements . .
while statements. . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

21
21
22
22

Chapter 6. Error handling . . . . . . . 23
try...catch...catchall...finally statements
throw statements . . . . . . .

.
.

.
.

.
.

.
.

. 23
. 24

Chapter 7. Creating scripts . . . . . . 25
Chapter 8. Displaying workflow
references . . . . . . . . . . . . . 27
Chapter 9. Editing workflow properties

.
.
.
.

.
.
.
.

.
.
.
.

Stopping a workflow that is running .

.
.
.
.

.

.
.
.
.

.

.
.
.
.

.

.
.
.
.

.

.
.
.
.

33
33
33
34

. 35

Chapter 13. Importing workflows . . . 37
Chapter 14. Exporting workflows . . . 39
Chapter 15. Displaying workflow run
history . . . . . . . . . . . . . . . 41
Exporting workflow run history logs .

.

.

.

.

. 41

Chapter 16. Displaying the run history
for an individual workflow . . . . . . 43
Chapter 17. Troubleshooting workflows 45
Chapter 18. Creating an automation
package . . . . . . . . . . . . . . 47
Step 1: Create the appropriate directory structure .
Step 2: Export the Oracle 9i workflow XML file .
Step 3: Export the shell scripts . . . . . . .
Step 4: Create the tc-driver.xml file . . . . .
Step 5: Copy and install the driver . . . . .
Automation package development standards . .
Naming your automation package . . . . .
Creating your tc-driver.xml file . . . . . .
Creating automation package documentation .

.
.
.
.
.
.
.
.
.

47
47
47
47
48
48
48
49
50

29

iii

iv

Workflow Developer’s Guide

Chapter 1. Preparing to write a workflow
A workflow template can be used as a starting place in building the workflows needed for your data
center. Using your workflow template you can define the order sequence, any pre-requisites that should
be reviewed, determine the exact intent of the workflow and understand any limitations that are inherent
with it, and define any input and output variables that you may require. Templates save time and
increase the precision of your design.
Your workflow template should detail the order of operation, but also highlight the potential limitations
that are involved with this action. A sample workflow template may look like this:
Table 1. Sample workflow template
Step

Description

Determine order sequence

Determine the sequence of events to gather the inputs
required to run the workflow. This includes calls for data
from the Data Center Model (DCM). For each workflow,
it is necessary to determine the variables (and their
order) that will be passed from the user interface. You
must then derive any associated inputs from this initial
set of inputs. For an example of how this is done, see the
Cluster.Remove Server template below.

Pre-requisite checks

Determine if all the key inputs and target resources for a
given workflow are correct and available before
proceeding. For example, if the workflow requires the
use of a software installation server, first check to see if
that server is available.
This step is necessary because it is difficult to run a
workflow to a point of failure and try and recover at that
stage.
Make sure that targets are available after you run a
workflow. For example:
v If you install an operating system on a server, create a
superuser, password, and a default route so Tivoli
Intelligent ThinkDynamic Orchestrator can still
connect to the new system.
v

If you move a port to another VLAN, then you will
want a recovery transition that moves the port back in
case a transition fails in the middle of a workflow.

1

Table 1. Sample workflow template (continued)
Standard template for recovery

Determine an appropriate recovery method for your new
workflow. Currently, Tivoli Intelligent ThinkDynamic
Orchestrator uses a recovery method workflow. To use a
recovery method at the parent workflow level:
1. Set a server’s state to maintenance.
2. Move the server out of a associated cluster and back
to the its resource pool.
3. Notify the Tivoli Intelligent ThinkDynamic
Orchestrator administrator.
Although this is a standard operation, it does not apply
to all situations, for example, recovery actions in
workflows against a network device. Network devices
are typically shared so any recovery action will typically
be an undo of what was performed. Another example is
a recovery action against a free pool. In this case, the
resource should be flagged and the Tivoli Intelligent
ThinkDynamic Orchestrator administrator should be
notified.

Template example: Cluster.Remove Server Logical Operation. Outlines the operations required to
remove server resources from a cluster.
Table 2. Template example: Cluster.Remove Server Logical Operation
Transition

Description

Get Current Deployment Request Id

Data gathering phase

Get Cluster Attributes

Data gathering phase

Get Pool Attributes

Data gathering phase

Get VLAN Attributes

Data gathering phase

Pre-requisite checking

Using information from the data gathering phase,
validate that the key components in the workflow are
available for use. In this workflow, an example would be
the software server responsible for uninstalling the
software products defined in the stack, and the existence
of the ACL ID’s to enable on the target firewall.

RM Choose Server for Removal

Resource Manager to select a random allocated server
from application cluster (dedicated servers will not be
affected).

Get Server Attributes

Get the server attributes, such as NICID, to use in
subsequent transitions.

Get NIC Attributes

Get the properties of the NIC.

Get Real IP Attr by Network Interface

Get the IP address of the Network Interface

Get Software Stack for Device

Determine the software stack associated with the server

LoadBalancer.Rmv Real IP from Virtual IP

Remove the servers real IP address from the VIP.

SoftwareStack.Uninstall

Remove the software products associated with the stack.

RM Allocate Ip Address

Get next available IP address for subnet of VLAN.

IPSystem.Add IP Address

Add IP to DCM.

IPSystem.Apply Routing Table

Update the routing table.

Switch.Move Port to VLAN

Move server from resource VLAN to production VLAN.

SNMP Ping

Verify that unmanaged interface can still be reached.

2

Workflow Developer’s Guide

Table 2. Template example: Cluster.Remove Server Logical Operation (continued)
Update SAPs for Group of Servers

Update the service access points for the server.

Related information
Workflows
Workflow composer
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Chapter 17, “Troubleshooting workflows,” on page 45

Chapter 1. Preparing to write a workflow

3

4

Workflow Developer’s Guide

Chapter 2. Tutorial: Creating a new workflow
The objective of this tutorial is to create a simple workflow that will display the contents of a current
working directory using the ls -l command.
Prerequisites:
1. Create a server representing the Tivoli Intelligent ThinkDynamic Orchestrator server. The server name
must be the same as the return value from hostname.
2. This server must be configured for an execute-command service access point (SAP).
Note: The above requirements should have already been done as part of your Tivoli Intelligent
ThinkDynamic Orchestrator installation.
To add a new workflow:
Important: It is very important during workflow development that you compile your workflow
consistently to save it in the database. To compile your workflow, select Compile → Compile .
Step 1: Create a new workflow
1. Click System configuration and workflow management → Workflows.
2. On the All Workflows page, click Edit → Add Workflow. The Workflow Composer is displayed.
3. Click Edit → Properties and type a new name for your workflow.
4. Click Locale Insensitive if you do not want to specify a particular locale. If a locale has been
specified, a workflow will fail if the target device for the workflow does not match the locale.
5. Click Edit → Save.
Step 2: Retrieve the device ID of the Tivoli Intelligent ThinkDynamic Orchestrator host server. This
workflow will run a command on the Tivoli Intelligent ThinkDynamic Orchestrator host. For that to
happen, the Deployment Engine will search for the name of the host on which it is running and will
search for a server device ID of that same name. To configure a transition to do this, click Java Plug-ins.
1. Select the Get Deployment Engine Device ID and drag-and-drop the plug-in to your workflow.
2. Next to the No operation transition, click Delete transition.
3. Click EditSave.
Step 3: Create a local variable for the server’s device ID. When we retrieve the device ID from the
deployment engine, we need a variable to hold that value. To do this:
1. Drag-and-drop the variable element to your workflow space.
2. Click Edit → Properties.
3. Create a new variable called DeviceID and click Save.
4. Expand the Get Deployment Engine Device ID Java plug-in.
5. Drag the DeviceID variable and drop it in the Value field.
Step 4: Create a transition to run the ls -l command
1. Expand Logical Devices.
2. Expand Device
3. Select Execute Command and drag-and-drop the logical device operation to your workflow.

5

4. You now need to create local variables for the ls -l command and the working directory. The
ExecuteCommand and WorkingDirectory variables are required variables in the Device.Execute
Command transition, so local variables must be created for them. To do this, drag-and-drop the
variable element to your workflow space.
5. Click Edit → Properties.

Sample workflow: Cisco Turn Port ON
Let’s examine an existing workflow in the Tivoli Intelligent ThinkDynamic Orchestrator product for a
better understanding of how a workflow is constructed and runs. We will assume, for this example, that
a workflow for this operation does not exist and we will need to create it.
The Cisco Turn Port ON workflow when run will turn a port associated with a Cisco switch on. To do
this, we need to follow five basic steps:
1. Acquire the switch ID associated with the Cisco switch and the port number that we want to turn on.
2. Lock the switch. When you turn a port on, the switch should not be accessible so that it is not
interfered with while you are changing its status.
3. Change the port status from OFF (shutdown) to ON (active).
4. Save the current configuration.
5. Unlock the switch.
Step 1: Create a new workflow
1. Click System configuration and workflow management → Workflows. The Workflow Composer is
displayed.
2. Click Edit → Properties and type a new name for your workflow.
3. Click Edit → Save. When prompted, click Save.
Step 2: Define parameters for the switch ID associated with the Cisco switch and the port number that
we want to turn on. At this point, we can start to build our workflow using the workflow build
components of the Tivoli Intelligent ThinkDynamic Orchestrator.
1. Expand your new workflow and drag-and-drop two parameter elements to your workflow build
space.
2. Click Edit → Properties.
3. Rename the first parameter SwitchID.
4. Rename the second parameter PortNumber.
5. Click Edit → Save. When prompted, click Save,
Step 3: Lock the switch. The switch should not be accessible while its status is changing. To do this:
1. Expand Java plug-ins.
2. Drag-and-drop the Lock DCM Object and Unlock DCM Object Java plug-ins to your new workflow.
Note: The optimal method to work with other workflows, while still having your new workflow in
view, is to open your new workflow first in the right-hand pane, and use the navigation tree to find
and work with other workflows and Java plug-ins.
3. Expand the Lock DCM Object transition and drag-and-drop the SwitchID parameter to the Value
field in the DCM Object ID parameter row.
4. Expand the Unlock DCM Object transition and drag-and-drop the SwitchID parameter to the Value
field in the DCM Object ID parameter row.
5. Delete the No operation transition.
6. Click Edit → Save. When prompted, click Save,

6

Workflow Developer’s Guide

Step 4: Add a transition to change the port status from OFF to ON
1. Expand Java plug-ins.
2. Locate the Cisco Change Port Status Java plug-in.
3. Drag-and-drop this plug-in to your new workflow so that it appears as the second transition in your
workflow.
4. Expand the Cisco.ChangePortStatus transition.
5. Drag-and-drop the SwitchID parameter to the Value field in the Device ID parameter row.
6. Drag-and-drop the PortNumber parameter to the Value field in the Port Number parameter row.
7. Click Edit → Properties in the New Port Status row.
8. Type On as the new value and click Save.
9. Click Edit → Save. When prompted, click Save,
Step 4: Add a transition to save your new port configuration
1. Expand Java plug-ins.
2. Locate the Cisco Save Configuration Java plug-in.
3. Drag-and-drop this plug-in to your new workflow.
4. Expand theCisco.SaveConfiguration transition.
5. Click Edit → Properties in the Device ID row.
6. Drag-and-drop the SwitchID parameter to the Value field in the Device ID parameter row.
7. Click Edit → Save. When prompted, click Save,
To run this workflow, click Build → Compile.
Related information
Workflows
Workflow components
Chapter 1, “Preparing to write a workflow,” on page 1
Chapter 3, “Creating a workflow using a text editor,” on page 9
Chapter 4, “Querying the data center model,” on page 13
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Chapter 17, “Troubleshooting workflows,” on page 45
“Data center model query language syntax” on page 17

Workflow development standards
The following development standards are recommended when creating workflows:

Chapter 2. Tutorial: Creating a new workflow

7

Workflow naming conventions
Tivoli Intelligent ThinkDynamic Orchestrator has two fields that identify individual workflows:
v A name field that is a maximum of 40 characters in length
v A description field that is a maximum of 2000 characters in length
1. It is recommended that workflows are named using a common syntax. The following syntax is
suggested:
<action>_<object>_on/at/in/from/to/using_<subject>

Note:
For example: Add_IP_address_to_virtual_server. If your transition does not fit this template, ensure
that it is descriptive enough to explain the intention of the transition, such as
Concatenate_the_source_path_and_ operating_system_strings.
2. The words that are used should be short and use terminology that is commonly applied in that
specific domain.
3. Use consistent terminology. For example, copy, get, acquire, retrieve could all potentially apply to the
same action. Use only one of these terms across all similar workflows.

Variable naming conventions
Use the following convention when naming variables:
v The first character is lowercase. For example, destination
v Use a continuous string without punctuation or white space.
v Concatenate and capitalize all component words within variable names. Do not connect the component
words with an underscore. For example, DeviceName.

Describing transitions and variables
All transitions and variables need to be described appropriately in their respective Description fields so
that the intention of the transition, variable, and workflow as a whole, can be understood.
Related information
Workflows
Workflow composer
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43

8

Workflow Developer’s Guide

Chapter 3. Creating a workflow using a text editor
There are two options that you can use to create a new workflow. You can use the web-based user
interface, or you can write your workflow in any text-based editor and import the workflow into Tivoli
Intelligent ThinkDynamic Orchestrator.
Important: It is very important during workflow development that you compile your workflow
consistently to save it in the database. To compile your workflow, select Compile → Compile .
1. Open a text-based editor and write your workflow.
2. Type a name for the workflow with the following naming convention: workflow <workflow name>
3. Type LocaleInsensitive if you are not concerned with a particular locale. If a locale has been
specified, a workflow will fail if the target device for the workflow does not match the locale. To
check a device locale, refer to the following example:
workflow test
var v = Jython("en_US")
var deviceId = Jython(5)
CheckDeviceLocale deviceId v
CheckDeviceLocale deviceId "fr_FR"

4. Type the contents of your new workflow. Refer to the example below and the looping and conditional
statements, and dcm queries for more information.
workflow DCM_Insert LocaleInsensitive
var server_id = "1018"
var vlan1 = "222"
var vlan2 = "700"
#1084 1086
DCMInsert <<EOINSERT
<subnetwork ipaddress="1.1.1.1" netmask="222.222.222.222">
<vlan vlan-number="700" fabric="Default Fabric"/>
</subnetwork>
EOINSERT
DCMInsert <<EOINSERT
<subnetwork ipaddress="1.1.1.1" netmask="222.222.222.222">
<vlan vlan-number="222" fabric="Default Fabric"/>
</subnetwork>
EOINSERT
DCMInsert <<EOINSERT
<switch name="lab00-sw1" is-device-model="Cisco 3548" fabric="Default Fabric" ipaddress="10.1.0.26" locale="en_US">
<switch-module name="0">
<switch-port vlan="$vlan1" port-number="27"/>
<switch-port vlan="$vlan2" port-number="29"/>
<switch-port vlan="$vlan1" port-number="30"/>
<switch-port vlan="$vlan1" port-number="31"/>
<switch-port vlan="$vlan1" port-number="32"/>
</switch-module>
<sap name="snmp get" app-protocol="SNMP" port="161" context="write" host="true" locale="en_US">
<credentials is-default="false" search-key="hp">
<snmp-credentials community="public"/>
</credentials>
</sap>
<sap name="snmp set" app-protocol="SNMP" port="161" context="read" host="true" locale="en_US">
<credentials is-default="false" search-key="hp">
<snmp-credentials community="public"/>

9

</credentials>
</sap>
</switch>
EOINSERT

DCMInsert <<EOINSERT
<boot-server name="ignite" locale="en_US">
<nic connected-to-switch="lab00-sw1" connected-to-module="0" connected-to-port="29" netboot-enabled="true" managed="fa
<network-interface name="lan0" ipaddress="1.1.1.1.1" managed="false"/>
</nic>
<sap name="ssh" port="22" host="true" app-protocol="SSH" locale="en_US">
<credentials search-key="hp" is-default="false">
<rsa-credentials username="root"/>
</credentials>
</sap>
<sap name="scp" port="22" host="true" app-protocol="SCP" locale="en_US">
<credentials search-key="hp" is-default="false">
<rsa-credentials username="root"/>
</credentials>
</sap>
</boot-server>
EOINSERT

server_id = DCMQuery(/server[@name="test"])
#DCMInsert parent = DCMQuery(/Server[@id = $server_id]) <<EOINSERT
DCMInsert parent = DCMQuery(/Server[@name = "test"]) <<EOINSERT
<network-interface name="workflow" ipaddress="1.1.1.1" managed="false"/>
EOINSERT

5. Save your workflow with a .wkf file extension.
6. In Tivoli Intelligent ThinkDynamic Orchestrator, click System configuration and workflow
management → Workflows.
7. Click Edit → Open.
8. Click Browse and navigate to the workflow that you had just created.
9. Click OK.
Related information
Workflows
Workflow components
Chapter 1, “Preparing to write a workflow,” on page 1
Chapter 2, “Tutorial: Creating a new workflow,” on page 5
Chapter 4, “Querying the data center model,” on page 13
Chapter 5, “Conditional and looping statements,” on page 21
Chapter 7, “Creating scripts,” on page 25
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43

10

Workflow Developer’s Guide

Chapter 17, “Troubleshooting workflows,” on page 45
“Data center model query language syntax” on page 17

Chapter 3. Creating a workflow using a text editor

11

12

Workflow Developer’s Guide

Chapter 4. Querying the data center model
Using the dcm query language, you can query the dcm database and have a result set returned. To query
the dcm and obtain attributes associated with a physical or logical asset:
1. On the Workflows page, select DCM Query.
2. Drag-and-drop the Variable element to your workflow build space. This variable will hold the value
that will be returned from your dcm query.
3. Click Edit → Properties and rename the variable. Click Save.
4. Drag-and-drop the DCM Query element to the row that contains your new variable in the workflow
build space.
5. Click the DCM Query element in your workflow.
6. In the Value field, type your dcm query.
7. Click Save.
A dcm query supports select, insert, update, and delete actions. When a workflow that contains a dcm
query successfully completes a requested change to the data center, the data center model is updated to
reflect the current data center infrastructure.
Note: Only one attribute of a dcm object can be retrieved at a time.
Refer to the following topics for more information on the proper syntax to use when creating your query.

Retrieving data from the dcm
To retrieve data from the dcm, use the DCMQuery command as shown in the examples below:
v To retrieve all NIC IDs that have a server name of Nile and that are not managed:
DCMQuery (/server[@name="Nile"]/nic[@managed="N"])

v To retrieve all the server names, ordered alphabetically by name, in the RiversEdge cluster:
DCMQuery (/cluster[@name="RiversEdge Web"]/server/@name[orderBy@name])

v To retrieve the server name in the RiversEdge cluster using a variable ($serverName) that had been
previously defined in a workflow:
DCMQuery (/cluster[@name="RiversEdge Web"]/server[@name=$serverName])

Note:
v Some objects have two fields that link to another object. For example, accessRule has
sourceSubnetwork and destinationSubnetwork attributes. To navigate from accessRule to a subnetwork
use:
– accessRule/sourceSubnetwork, or
– accessRule/destinationSubnetwork
instead of accessRule/subnetwork. For example:
DCMQuery(/acl[@name="acl-1 New1"]/accessRule/sourceSubnetwork/@ipaddress)

v A relationship between two dcm objects can be navigated using a dcm query in two directions. For
example:
– /server[@name=\"Server1\"]/bladeadminserver or,
– bladeadminserver [@name=\"Blade1\"]/server

13

Aliases are used to differentiate between relationships. For example, in the query below, accessRule
has two fields connecting to a subnetwork: sourceSubnetwork and destinationSubnetwork. Two
relationships were generated for this scenario, one for each relation field:
/acl[@name="acl-1 New1"]/accessRule/sourceSubnetwork/@ipaddress
/acl[@name="acl-1 New1"]/accessRule/destinationSubnetwork/@ipaddress

In order to navigate in the opposite direction, you must use an alias object to differentiate between the
relationships. For example:
– /subnetwork[@ipaddress="10.1.8.0"]/AclRuleSource/acl/@name: Will link the subnetwork to the
sourceSubnetwork field from the accessRule.
– subnetwork[@ipaddress="10.1.8.0"]/AclRuleDestination/acl/@name: Will link the subnetwork to
the destinationSubnetwork field from the accessRule.

Inserting data in the dcm
When you insert data into the dcm, it is assumed that the object does not already exist and you are
creating it for the first time. Your XML data consists of top-level and embedded elements and,
consequently, there are two methods for inserting data into the dcm. To insert data into the dcm, use the
DCMInsert command as shown in the examples below:
Inserting a top-level object: If a top-level object is being added to the dcm, the only requirement is the
DCMInsert command and the XML data. For example, to insert a new blade server chassis that is not
managed, has a network interface name of Management network, and an IP address of 10.1.8.77:
DCMInsert <<EOF
<blade-admin-server name="blade-chassis-admin">
<network-interface name="Management network" ipaddress="10.1.8.77" managed="false"/>
</blade-admin-server>
EOF

Note: When you insert a top-level object (parent) into the dcm using the web-based user interface, you
do not have to specify a parent element in the Parent field.
Inserting an embedded element: If a child element is being added to the dcm, you must first retrieve the
parent element’s ID to determine the location in the dcm where the new data should be added. In the
following example, the parent element is Customer, and the DCMInsert parent =
DCMQuery(/customer[@name="Rivers Edge Retail"]) expression will retrieve the Customer ID, and using
this ID, can determine the precise location in the XML that will contain the new data.
DCMInsert parent = DCMQuery(/customer[@name="Rivers Edge Retail"]) <<EOF
<application name="Online Store New" priority="5">
<cluster name="RiversEdge Web" virtual-ipaddress="10.1.1.132"
virtual-tcp-port="80" min-servers="2" max-servers="10" pool="Apache-Redhat" vlan="510"
tier ="1" fabric="Default Fabric"/>
</application>
EOF

The remaining details associated with this example:
v A new application is added to the River’s Edge Retail customer called Online Store New.
v Together with a new application, a new cluster is being added called RiversEdge Web, that has a
virtual IP of 10.1.1.132, and a virtual IP port of 80, a vlan of 510, and belongs to the Apache-RedHat
resource pool and Default Fabric switch fabric. This cluster must have a minimum of 2 servers and a
maximum of 10.
Note: You cannot define a new service access point without defining proper credentials (password,
SNMP, RSA). This credential makes sense only in the context of a service access point, as shown in the
following example:

14

Workflow Developer’s Guide

DCMInsert parent = DCMQuery(/terminalServer[@name=\"Console Server New1\"]) <<EOF
<sap name=\"telnetd-5201 New1\" port=\"5201\" app-protocol=\"Telnet\" host=\"true\">
<credentials search-key=\"primary\" is-default=\"false\">
<password-credentials username=\"primary\" password=\"bingo\"/>
</credentials>
</sap>
EOF

Updating data in the dcm
To update data in the dcm, use the DCMUpdate command as shown in the example below:
DCMUpdate (/cluster[@name=\"RiversEdge Web1\"]) <<EOF
<cluster name=\"RiversEdge Web2\" is-device-model=\"Simulator\" min-servers=\"2\" max-servers=\"10\"
pool=\"IIS-Win2K New1\" vlan=\"0001\" tier =\"1\" fabric=\"Default Fabric New1\"/>
EOF

Note: You can only update one object at a time, so embedded objects cannot be updated at the same time
you update a top-level object.

Deleting data from the dcm
To delete data from the dcm, use the DCMDelete command, as shown in the example below:
v To delete a customer application with a name of Online Store:
DCMDelete (/application[@name="Online Store"])

v To delete a customer application with an ID of 123:
DCMDelete (/application[@id="123"])

Note:
v You cannot delete an object that cannot be identified through a single ID (the primary key is composed
from several fields).
v You can delete all properties for a specific object, but you cannot delete a specific property for an
object.
v Cascading delete is not supported in the dcm query language. If a dcm object that you want to delete
has a relationship to other dcm objects, those objects must be deleted first. For example, to delete a
router switch, you have to delete the router first and then the corresponding switch.

Retrieving properties of a dcm object
The properties associated with dcm objects can also be managed using dcm queries in the workflow
composer. The DCMQuery, DCMInsert, DCMDelete, and DCMUpdate commands are all supported when
working with the properties of dcm objects.
To retrieve the properties of an object, you must specify the ID of the object whose properties you want
to retrieve. You can do this using the DCMQuery command as shown in the example below.
COMPONENT_ID

KEY

ID

VALUE

0

snmp.community.read

1234

public

0

snmp.community.write

3333

public

0

tcdriver-version

4444

public

If your properties table has the elements shown above, you can retrieve a property value for a given key:
DCMQuery (/softwareStack[@id="1234"]/property[@componentId="0"]/@snmp.community.read)
Chapter 4. Querying the data center model

15

Note: You do not have to specify the component ID. The system assumes that the value is 0 if it has not
been explicitly defined in the query. For more information on the Tivoli Intelligent ThinkDynamic
Orchestrator components and IDs, refer to: Numeric representation of dcm components

Inserting properties into the dcm
Using the DCMInsert command, you can insert new properties by doing the following steps:
1. Retrieve the ID of the object that will obtain new property values. For example, to start building the
query to insert new properties for a Windows 2000 Server software stack, type: DCMInsert parent =
DCMQuery(/softwareStack[@name="Windows 2000 Server"]) <<EOF
2. Write the XML expression to insert a value of snmp.community.read as the Key and public as the
Value, followed by EOF:
<property name="snmp.community.read" value="public"/>
EOF

3. The complete dcm query looks like the following:
DCMInsert parent = DCMQuery(/softwareStack[@name="Windows 2000 Server"]) <<EOF
<property name="snmp.community.read" value="snmp.community.read"/>
EOF

Updating the properties of a dcm object
To update the properties of a dcm object (in this example, the Windows 2000 Server software stack), three
values are needed: an ID of the object whose properties you want to change, the key field for this value,
and the component ID. A properties table in the dcm may look like the following. The first line that is
highlighted in the table is associated with the Windows 2000 Server software stack.
COMPONENT_ID

KEY

ID

VALUE

0

snmp.community.read

2222

public

0

snmp.community.write

3333

public

0

tcdriver-version

4444

public

Using the DCMUpdate command, you can change the data in this table by doing the following steps:
1. Use a dcm query to determine the ID of the object.
2. Determine the component ID. You will have to obtain this value from the properties table in the
Tivoli Intelligent ThinkDynamic Orchestrator application database.
3. Determine the key value associated with this Windows 2000 Server software stack. For this example,
assume that it is snmp.community.read.
4. Write the XML expression to change the Value property to private.
5. The complete dcm query looks like the following:
DCMUpdate object = DCMQuery(/softwareStack[@name="Windows 2000 Server"]) <<EOF
<property name="snmp.community.read" value="private">
EOF

Deleting the properties of a dcm object
It is not possible to delete a specific property that is associated with a dcm object, so when a DCMDelete
query is run, all properties associated with that object are deleted from the dcm. To delete the properties
of a dcm object, use the DCMDelete command as shown in the example below:
v To delete the properties of a software stock with an ID of 1096 and a component ID = 0:
DCMDelete (/softwareStack[@id="1096"]/property)

16

Workflow Developer’s Guide

Related information
“Data center model query language syntax”
Data center model
Workflow composer
Creating and managing workflows
Numeric representation of dcm components

Data center model query language syntax
The dcm query language uses an XPath-like syntax to select elements from the dcm database that match
the path. The following is a syntactically valid dcm query language input:
DCMQuery(/server[@name="Nile"]/nic[@managed="N"])

This particular expression retrieves the NIC IDs of a server with a name of Nile and whose network
interface cards are not managed. The ID value will always be returned by default unless another return
attribute has been explicitly declared. Refer to Chapter 4, “Querying the data center model,” on page 13
for more information.
When you work with the Workflow Composer and drag-and-drop the DCM Query element to the
workflow build space, you can create a dcm query to use with your workflow. All dcm queries must
begin with a command such as DCMQuery, DCMInsert, DCMDelete, or DCMUpdate. In the expression above,
server and nic are examples of elements, while name and managed are examples of attributes. They
identify names of tables and columns from the database.

Reading dcm query language expressions
A dcm query language expression is a slash-separated list of element names that describe a path through
a relational database. It uses elements, attributes, operators, and conditions that describe a path through a
relational database. When you read a dcm query expression, the far most element on the right-hand side
of the expression is the data that the query expects to retrieve. For example, in the following expression:
DCMQuery(/server[@name="Nile"]/nic[@managed="N"])

the query will retrieve all of the NICs that are not managed, and belong to a server with the name Nile.
Grammar notation
The dcm query language uses the Extended Backus-Naur Form (EBNF) for grammar notation. EBNF is a
set of rules that describe a specific fragment of syntax If you can reduce a document to a single rule with
no further input, it is considered valid. The following table describes the dcm query language using
EBNF grammar:
dcmQuery ::=

’/’step (xQuery)?

xQuery ::=

( ’/’ step )*( ’/’ finalExpr )? | ’/’ finalExpr

step ::=

object ( ’[’ condExpr ’]’ )?

finalExpr ::=

attribute (’[’ orderByExpr ’]’ )?

condExpr ::=

equalExpr (’and’ equalExpr)*

equalExpr ::=

attribute ’=’ (value | variable)

orderByExpr ::=

orderBy attribute

object ::=

letter (letter | digit )*

attribute ::=

’@’letter (letter | digit |’ -’| ’.’|’_’)*

variable ::=

’$’letter(letter | digit |’.’|’_’)*

Chapter 4. Querying the data center model

17

value ::=

’″’ (any character except ″)* ’″’

v The | operator builds the union of two types. For example, the expression: (letter | digit ) means that
an element of type letter or type digit.
v An asterisk (*) symbol at the end of a syntax rule corresponds to zero or more instances of that type.
v A question mark (?) symbol at the end of a syntax rule corresponds to zero or one instance of that
type.
Dcm query language parts and expressions
Part

Syntax rule

Value

’″’ (any character except ″)* ’″’

Object

letter (letter | digit )*
This expression should be read as follows: An object consists of a letter
followed by zero or more instances of a letter or a digit.
Example: DCMQuery(/server[@name="Nile"]/nic[@managed="N"]). An object
in this query is server.

Attribute

@letter (letter | digit |’ -’| ’.’|’_’)*
This expression should be read as follows: An attribute consists of an @
symbol followed by a letter, followed by zero or more instances of a letter,
digit, hyphen, period, or underscore.
Example: DCMQuery(/cluster[@name="RiversEdge
Web"]/server/@name[orderBy@name]). The attribute in this query is @name.

Variable

’$’letter(letter | digit |’.’|’_’)*
This expression should be read as follows: A variable consists of a $ symbol
followed by a letter, followed by zero or more instances of a letter, or digit,
or period, or underscore.
Example: DCMQuery(/deploymentPlan[@id=$dpId]/servers/server). The
variable in this query is: $dpId.

Order by expression (orderByExpr)

orderBy attribute
This expression should be read as follows: An order by operand consists of
an orderBy expression followed by an attribute.
Example: DCMQuery(/cluster[@name="RiversEdge
Web"]/server/@name[orderBy@name]). The order by expression in this query
is orderBy@name.

Equal expression (equalExpr)

attribute = (value|variable)
This expression should be read as follows: An equal expression consists of
an attribute followed by an equal sign, and followed by a value or a
variable.
Example: DCMQuery(/cluster[@name="RiversEdge
Web"]/server/@name[orderBy@name]). The equal expression in this query is:
@name="RiversEdge Web".

Conditional expression (condExpr)

equalExpr( and equalExpr)*
This expression should be read as follows: A conditional expression consists
of an equal expression followed by zero or more instances of an AND
operator and an equal expression.
Example: @managed="N" AND @name="NIC01" AND @netbootEnabled="N" AND
@macaddress="<null>"

18

Workflow Developer’s Guide

Final expression (finalExpr)

attribute ( ’[’ orderByExpr ’]’ )?
This expression should be read as follows: A final expression consists of a
an attribute followed by an open square bracket, followed zero or one
instance of an order by expression, followed by a closed square bracket.
Example: DCMQuery(/cluster[@name="RiversEdge
Web"]/server/@name[orderBy@name]). The final expression in this query is:
@name[orderBy@name].

Step

object (’ [ ’condExpr’ ]’ )?
This expression should be read as follows: A step expression consists of a an
object followed by an open square bracket, followed by zero or one instance
of an conditional expression, followed by a closed square bracket.
Example: DCMQuery(/server[@name="Nile"])

xQuery

( ’/’ step )* ( ’/’ finalExpr ) ? | ’/’finalExpr
This expression should be read as follows: An xQuery expression consists of
zero or more instances of a step followed by zero or one instance of a final
expression or only a final expression .
Example: DCMQuery(/server[@name="Nile"]/nic[@managed="N" AND
@name="NIC01" AND @netbootEnabled="N" AND
@macaddress="<null>"]/@name[orderBy@name])

dcmQuery

’/’step (xQuery)?
This expression should be read as follows: A dcmQuery expression consists
of a step, followed zero or more instances of an xQuery.
Example: DCMQuery(/server[@name="Nile"]/nic[@managed="N" AND
@name="NIC01" AND @netbootEnabled="N" AND
@macaddress="<null>"]/@name[orderBy@name])

Note:
v A dollar sign ($) in a dcm query expression followed by letters or digits is used to represent a variable
in a dcm query.
v Brackets ([]) in a dcm query expression are used to group conditional and order by expressions.
v A back slash (/) in a dcm query expression represents an absolute path to the required element.
v Attributes are specified by a @ prefix and are separated from values by an equal (=) sign in a dcm
query expression.
v Values are enclosed in double quotes (″ ″) in a dcm query expression.
v To use a value that contains a double quote, you can define a variable that has that value and use the
variable instead in the query.
v To define a null value, use "<null>". For example, @name="<null>"
Related information
Data center model queries
Data center model
Chapter 4, “Querying the data center model,” on page 13
Workflow composer
Creating and managing workflows
Numeric representation of dcm components

Chapter 4. Querying the data center model

19

20

Workflow Developer’s Guide

Chapter 5. Conditional and looping statements
A loop is used in programming to allow you to perform one or more actions repeatedly. As long as a
statement evaluates to true, the loop will repeat and will run an indefinite number of times until the
expression evaluates to false. A conditional tests an expression using an if statement, and uses a then
statement to show alternative actions to run if the expression is false. If the expression is never true, the
action is not performed
Related information
“if...then statements”
“if...then...else statements”
“foreach statements” on page 22
“while statements” on page 22

if...then statements
Purpose
The if...then statement is a basic conditional statement. To perform an operation if an expression is true,
use an if statement to test an expression and use a then statement to show alternative actions to run if
the expression is false
Sample
The following example shows how the if...then conditional statement works:
workflow test
if Jython(mycondition) then
statement
endif

Related information
“if...then...else statements”
“foreach statements” on page 22
“while statements” on page 22

if...then...else statements
Purpose
The if...then...else statement is a basic conditional statement. To perform an operation if an expression is
true, use an if statement to test an expression and use a then statement to show alternative actions to
run if the expression is false, and optionally, an else statement for other alternative actions.
Sample
The following example shows how the if...then...else conditional statement works:
workflow test
if Jython(mycondition) then
statements
else
statements
endif

Related information

21

“if...then statements” on page 21
“foreach statements”
“while statements”

foreach statements
Purpose
A foreach statement loops as long as a condition evaluates to true. This loop will repeat while the
condition is true and statements following do will run an indefinite number of times until the conditional
expression evaluates to false. Typically, you would use a while...do loop when the number of times that
you will run through a conditional is unknown. When you anticipate that your loop will repeat a specific
number of times, a foreach statement is a better choice and will repeat until a specified condition is false.
Sample
The following example shows how the foreach loop statement works:
workflow workflow1
foreach iteratorVar in DCMQuery(a DCM query) do
statement
done

Related information
“if...then statements” on page 21
“if...then...else statements” on page 21
“while statements”

while statements
Purpose
A while statement loops as long as a condition evaluates to true. This loop will repeat while the
condition is true and statements following do will run an indefinite number of times until the conditional
expression evaluates to false.
Sample
The following example shows how the while conditional statement works:
workflow workflow1
while Jython(condition) do
statement
done

Related information
“if...then statements” on page 21
“if...then...else statements” on page 21
“foreach statements”

22

Workflow Developer’s Guide

Chapter 6. Error handling
Error handling allows you to recover from unexpected errors. An error is a condition which, if not
handled, will cause the workflow to fail. When an error occurs in a workflow, you can use error handling
techniques to allow the workflow to recover on its own and shift the error to other less obtrusive areas of
the workflow.
Within the Tivoli Intelligent ThinkDynamic Orchestrator workflow design, all error handling is done by
throwing and catching errors. Using this method, you can protect the entire workflow from failing. The
following error handling techniques are supported in the workflow language:
Related information
“try...catch...catchall...finally statements”
“throw statements” on page 24

try...catch...catchall...finally statements
Purpose
Implements error handling for workflow development. Try statements are used with the intention of
catching errors in your workflow. If an error is thrown from the try statement, the catch statement is used
to catch a given class of errors and must be prepared to handle the errors that are thrown. When try
statements are run and errors have been handled, all finally statements are run.
Sample
The following example shows how the try...catch...catchall...finally exception handling works:
workflow TryCatchCatchAllFinally(in LString, in RString, out Output) LocaleInsensitive
try
Output=Jython(LString+RString)
catch MyException ex1
Output=Jython(LString+"catch MyException")
catch OtherException
Output=Jython(LString+"catch OtherException")
catchall ex3
Output=Jython(LString+"catchall")
finally
Output=Jython(LString+"finally")
endtry

Arguments
try
Required. Statements where an error can occur.
catch
Optional. Statements to handle errors that occur in a try statement.
catchall
Optional. Statements to catch exceptions of any type that occur in a try statement.
finally
Optional. Statements that are run after all error processing has completed.
Related information
“throw statements” on page 24

23

throw statements
Purpose
The throw statement generates an error condition that can be handled by the try...catch...catchall...finally
statement.
Sample
The following example shows how the throw exception handling works:
workflow ThrowExplicitMessage LocaleInsensitive
throw AnException "A message"

Arguments
throw
Optional. Statements that are passed to another area of the workflow.
Related information
“try...catch...catchall...finally statements” on page 23

24

Workflow Developer’s Guide

Chapter 7. Creating scripts
The workflow composer works with the Jython programming language to support embedded scripting in
Bash, Perl, and Expect.
To add a script to your workflow:
1. In Tivoli Intelligent ThinkDynamic Orchestrator, click System configuration and workflow
management → Workflows.
2. Drag-and-drop the Scriptlet element to your workflow build space.
3. Click the scriptlet language link.
4. Type the name of the scripting language that was used to write the script.
5.
6.
7.
8.

Type the target for the script. The target is a dcm query that resolves to a device ID.
Type the credentials key for the script.
In the Scriptlet Code field, type the script for your workflow.
Click Save.

A workflow with a sample script is shown below:
workflow test
scriptlet language = jython <<EOF
jython script
EOF
scriptlet language = perl target = DCMQuery($server) <<EOF
perl script
EOF
scriptlet language = perl target = DCMQuery($server) credentialskey = "key" <<EOF
perl script
EOF

Related information
Workflows
Workflow components
Chapter 1, “Preparing to write a workflow,” on page 1
Chapter 2, “Tutorial: Creating a new workflow,” on page 5
Chapter 4, “Querying the data center model,” on page 13
Chapter 5, “Conditional and looping statements,” on page 21
Chapter 7, “Creating scripts”
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Chapter 17, “Troubleshooting workflows,” on page 45
“Data center model query language syntax” on page 17

25

26

Workflow Developer’s Guide

Chapter 8. Displaying workflow references
Workflow references include all the data center objects associated with the selected workflow, as well as
any other workflows that reference it.
To display workflow references:
1. Click System configuration and workflow management → Workflows. The Workflows tab is
displayed.
2. In the list, select the workflow whose data you want to display.
3. Click the References tab.
All workflows using the current workflow, as well as all data center objects that are associated with this
workflow, are displayed.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Displaying the run details of a workflow
Deleting the run history of a workflow
Troubleshooting workflows

27

28

Workflow Developer’s Guide

Chapter 9. Editing workflow properties
To edit the properties of an existing workflow:
1. Click System configuration and workflow management → Workflows. The Workflows tab displays all
the workflows that are currently defined in the system.
2.
3.
4.
5.

In the workflow list, find the workflow whose properties you want to edit and click
Click Edit.
Edit the workflow properties as required.
Click Save.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties”

.

Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Troubleshooting workflows

29

30

Workflow Developer’s Guide

Chapter 10. Adding and managing workflow transitions
Transitions are steps within a workflow that are needed to run in sequential order to complete the larger
workflow. You can add, edit, and delete transitions as well as map the variables for your workflow.

Adding a new transition to the workflow
To add a new transition:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. In the navigation tree, identify the workflow, command, Java plug-in, or logical operation you want to
add as a new transition to your workflow, and then drag it onto your workflow’s editing area, in the
right frame. You can also copy transitions from already existing workflows, by dragging them either
from the navigation tree or from another browser window onto your workflow transition area. In this
case, a copy of the selected transition is created in your workflow.
3. If necessary, use the same drag-and-drop functionality to rearrange the transitions within your
workflow.
Related information
Creating and managing workflows

Editing transition properties
To edit the properties of a transition:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with.
2.
3.
4.
5.

In the transition list, identify the transition to edit, and then click
Click Properties.
Edit the transition properties as required.
Click Save.

.

Mapping a command variable
To map a command variable to a workflow parameter:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. Select an output variable and drag it to the Value field associated with the appropriate input
parameter.
3. Repeat step 2 and 3 for every transition that requires variable mapping.

Removing a transition
To remove a transition from the current workflow:

31

1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. In the list, identify the transition you want to remove and click
3. Click Delete.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29

.

Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Troubleshooting workflows

32

Workflow Developer’s Guide

Chapter 11. Adding and managing workflow variables and
parameters
For every workflow defined in the system, a set of input parameters and output variables can be
configured and mapped.
v The input parameters represent the initial set of data required by the workflow to perform its actions
v The output variables represent the values that result from actions performed by the workflow.
Managing workflow variables involves:
1. Adding a new variable
2. Removing a variable mapping
3. Deleting a variable

Adding a new variable
To add a new variable to the current workflow:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. Expand the top row in the workflow build space.
3. Drag-and-drop the variable element in the Workflow Composer to your workflow build space.
4. Click

and click Properties.

5. Type a name for the new variable.
6. Click Save.

Mapping a variable
To map a variable:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. Expand the transition that you want to work with.
3. Identify the variable that you want to map and drag it to the Value field associated with the input
parameter.

Removing a variable mapping
To remove a variable mapping:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. Expand the transition that you want to work with.
3. Identify the variable mapping that you want to remove, and click
4. Click Unbind.
5. When prompted, click OK.

.

33

Deleting a variable
To remove a variable from the current workflow:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with. The Workflow tab is displayed.
2. Expand the top row in the workflow build space.
3. In the variable list, identify the variable you want to remove, click
4. When prompted, click OK.
Related information

and then click Delete.

Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 14, “Exporting workflows,” on page 39
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Troubleshooting workflows

34

Workflow Developer’s Guide

Chapter 12. Running workflows
To run a workflow:
1. Click System configuration and workflow management → Workflows. The All Workflows page
displays the workflows currently defined in the system.
2. In the list, select the workflow that you want to run and click
.
3. Click Run.
4. If necessary, type the input parameters that are required to run the workflow and click Save.

Stopping a workflow that is running
To stop a workflow that is running:
1. After you have run a workflow, the Deployment Requests page is displayed. On that page, find the
deployment request that you want to work with. Each deployment request is identified by a Create
Time and Status.
2. Click Execution Logs.
3. On the Execution Logs page, click Stop Execution.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Troubleshooting workflows

35

36

Workflow Developer’s Guide

Chapter 13. Importing workflows
You can import a workflow from a specified .wkf source file. To import a workflow:
1. Click System configuration and workflow management → Workflows.
2. On the Workflow Composer page, click Edit → Open.
3. Click Browse and navigate to the .wkf source file to import.
4. Click OK.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 14, “Exporting workflows,” on page 39
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 15, “Displaying workflow run history,” on page 41
Troubleshooting workflows

37

38

Workflow Developer’s Guide

Chapter 14. Exporting workflows
A workflow can be exported either to the screen for viewing purposes, or to a specified file:
1. Click System configuration and workflow management → Workflowsand select the workflow that
you want to work with.
2. Click the Edit → Export.
3. Click Save.
4. Type the name of your workflow and save it as a .wkf file.
5. Click Save.
Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Displaying the run details of a workflow
Deleting the run history of a workflow
Troubleshooting workflows

39

40

Workflow Developer’s Guide

Chapter 15. Displaying workflow run history
To display the run history for all the workflows in the system:
1. Click System configuration and workflow management → Workflow Executions .
2. In the Workflow Name list, select a specific workflow or select All to view all workflows with a run
history.
3. Select a status of all, success, failed, in-progress or created from the Status list.
4. In the From and To lists, specify the time interval that you are interested in.
5. Click Search. The table displays the history for all of the workflows available in the system, according
to your criteria.

Exporting workflow run history logs
You can export the log files of your workflow history to help troubleshoot any workflow problems. The
workflow run logs are exported into an XML file with a filename that you specify.
v On a Windows platform, type the following command: workflowLogExport.cmd {-n<workflow_name>}*
{-f<export_filename>} {-i<input_filename>}.
v On a UNIX platform, type the following command: workflowLogExport.sh {-n<workflow_name>}*
{-f<export_filename>} {-i<input_filename>}
For example:
workflowLogExport.cmd -nMyWorkflow1 -n"MyWorkflow2" -f"c:/myDirectory/myWorkflowExport.xml"
workflowLogExport.cmd -i"c:/myDirectory/myExportWorkflowList.txt"

41

42

Workflow Developer’s Guide

Chapter 16. Displaying the run history for an individual
workflow
To display the run history for an individual workflow:
1. Navigate to the Tivoli Intelligent ThinkDynamic Orchestrator home page.
2. Filter the displayed run data by Request ID.
A record is displayed for each time that a workflow is run, and includes data such as, the request
number, the name of the workflow, the date and time that it was run, the name of the user who made the
request, as well as the run status.
In the case of a workflow with a longer run history, you can filter the run data to be displayed, using a
combination of the date and time, cluster, pool, and request ID as search criteria.
Search criteria

Description

Date Time

The date and time that the workflow was run. You can
choose from: last 2h, last 24h, last 48h, last week, last
month, last year.

Cluster

The cluster that contains the current workflow.

Pool

The resource pool that supported used when the
workflow was run.

Request ID

The request identifier of the workflow.

Related information
Workflows
Workflow components
Workflow composer
Preparing to write a workflow
Tutorial: Creating a new workflow
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31
Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow”
Troubleshooting workflows

43

44

Workflow Developer’s Guide

Chapter 17. Troubleshooting workflows
All deployment engine run-time results are logged to the $TC_HOME/logs/de/console.log file. If you are
looking for additional details to help determine why a particular transition within a workflow has failed,
review this log file first.
The standard functionality of Tivoli Intelligent ThinkDynamic Orchestrator is to suppress stack trace Java
exception error messages within the user interface, and the actual commands that have been run and
issued by the deployment engine at each transition. It is important that you understand exactly which
commands are being issued by the deployment engine at runtime (for debug purposes), and to achieve
this, you must enable debug mode in two places:
v The log4j.prop file within/config/log4j.prop should have lines that read:
log4j.appender.errorfile.threshold=debug
log4j.appender.consolefile.threshold=debug

Or, in the absence of either of these two lines, a single line that reads log4j.rootCategory=DEBUG,
consolefile, errorfile. This sets the consolefile and errorfile thresholds to debug should their
specific threshold not be set.
Note: This is default functionality. Debug mode is enabled for console.log files for a standard install.
v By only configuring the log4j settings, debug mode (default) will still suppress stack trace error
messages from the error window within the Tivoli Intelligent ThinkDynamic Orchestrator user interface
when you run workflows, but will not log actual commands issued by the deployment engine. To
enable this level of logging, you must define a global variable. To do this:
1. Click Configuration and click the Variables tab.
2. Name the variable debug, with a component of Deployment Engine, and a value of true.
This will enable full debug mode when you run workflows for both the Tivoli Intelligent
ThinkDynamic Orchestrator user interface and the log file.
Note: When you add this variable, the change takes effect immediately for each instance that a
workflow is run.
For all errors that occur when you run your workflow, check the run history. To do this:
1. Click System configuration and workflow management
2. Click Workflow executions
3. Select your workflow
Related information
Workflows
Workflow components
Workflow components
Chapter 1, “Preparing to write a workflow,” on page 1
Chapter 2, “Tutorial: Creating a new workflow,” on page 5
Chapter 4, “Querying the data center model,” on page 13
Chapter 8, “Displaying workflow references,” on page 27
Workflow references include all the data center objects associated with the selected workflow, as well
as any other workflows that reference it.
Chapter 9, “Editing workflow properties,” on page 29
Chapter 10, “Adding and managing workflow transitions,” on page 31

45

Chapter 12, “Running workflows,” on page 35
Chapter 11, “Adding and managing workflow variables and parameters,” on page 33
Chapter 13, “Importing workflows,” on page 37
Chapter 15, “Displaying workflow run history,” on page 41
Chapter 16, “Displaying the run history for an individual workflow,” on page 43
Chapter 17, “Troubleshooting workflows,” on page 45
“Data center model query language syntax” on page 17

46

Workflow Developer’s Guide

Chapter 18. Creating an automation package
When creating a new set of drivers for managing a resource, you should include all the high level logical
operations for that device model that apply. Include only those components in the driver that uniquely
apply to this solution. There may be other dependencies, but these should be referenced by specifying the
dependencies in the tc-driver manifest. For example:
<dependencies>
<dependency name="Core"/>
<dependency name="Image-Software-Stack"/>
</dependencies>

There may not always be a one to one relation in between device drivers and packages. If there are
operations that are shared between device drivers consider packaging them together. For example, when
packaging the drivers for the load balancer BipIP, the 3.3 and 4.1 versions were packaged together.
To create a new automation package:
Note: This documentation is using a Test Uninstall Oracle 9i workflow as an example.

Step 1: Create the appropriate directory structure
Create the following directory structure:
oracle/
oracle/bin
oracle/doc
oracle/repository
oracle/TC-INF
oracle/workflow

Step 2: Export the Oracle 9i workflow XML file
1.
2.
3.
4.
5.

Click the System configuration and workflow management tab.
Click Workflows.
Click the Test Uninstall Oracle 9i workflow.
On the Workflow Composer page, click Edit → Save.
Save the Test Uninstall Oracle 9i.wkf file to the oracle/workflow directory.

Step 3: Export the shell scripts
If you have any shell scripts that you used when creating a workflow, you need to copy these scripts to
the <TC_HOME>/bin directory.
1. Locate your uninstall.oracle9i.sh file that was used to uninstall the Oracle 9i product.
2. Copy that file to the oracle/repository directory.

Step 4: Create the tc-driver.xml file
A sample tc-driver XML file would look like the following:
<?xml version="1.0" encoding="UTF-8"?>
<tc-driver>
<tc-driver-format>1.0</tc-driver-format>
<driver-name>Oracle9i</driver-name>
<version>1.0</version>

47

<dependencies>
<dependency name="Core"/>
</dependencies>
<property name="tc.pkg" location="com.thinkdynamics.kanaha.tcdrivermanager.action"/>
<actions>
<action name="copy-file" class="${tc.pkg}.CopyFileActions"/>
<action name="driver" class="${tc.pkg}.DriverTypeActions"/>
<action name="workflow" class="${tc.pkg}.TxtWorkflowAction"/>
</actions>
<items>
<item name="repository/uninstall.oracle9i.sh" action="copy-file">
<param name="dest.path" value="${tc.home}/repository/oracle/uninstall.oracle9i.sh"/>
<param name="chmod" value="755"/>
</item>
<item name="workflow/Test Uninstall Oracle 9i.wkf" action="workflow" />
</items>
<device-models>
<device-model name="Oracle 9i install" category="Software Products">
<workflow name="Test Uninstall Oracle 9i"/>
</device-model>
</device-models>
<!-<post-install-workflow name="workflow name">
<param name="command variable name" value="value>
</post-install-workflow>
-->
</tc-driver>

1. Create the tc-driver.xml file like the sample given above and save it in UNIX text format.
2. Copy the tc-driver.xml manifest file to the oracle/TC-INF directory.

Step 5: Copy and install the driver
1. Copy the driver to the to the %TC_HOME%/drivers directory.
2. Change the directory to: %TC_HOME%/tools
3. Run tc-driver-manager.cmd installDriver <automation package name>. On non-Windows systems,
run the tc-driver-manager.sh command.
Note: This step assumes that we are not repackaging any existing Oracle 9i solutions in this package. You
should include all the high level logical operations for a device model that apply.
Related information
Automation package manager
Automation package manager is a utility that manages automation packages . It requires a
configuration file, $TC_HOME/config/tcdrivermanager.xml, that defines the location of the directory
holding the drivers, and any other properties definitions that are common to all automation packages.
It also uses the dcm.xml and objectview.prop files for database connection information. The
automation package manager can run independently from any other Tivoli Intelligent ThinkDynamic
Orchestrator engines.

Automation package development standards
The following development standards are recommended when creating automation packages:

Naming your automation package
When you create a new automation package, use the following naming conventions:
v The first letter of the automation package should be lowercase.
v Multiple words should be separated by a hyphen. For example: extreme-48i.
v The automation package must have a .tcdriver extension.

48

Workflow Developer’s Guide

A proper automation package name would be: extreme-48i.tcdriver.
v The name that you choose should be exactly the same name that you specify between the
<driver-name> </driver-name> tags in your tc-driver.xml file. For example: <driver-name>extreme48i</driver-name>. Refer to “Creating your tc-driver.xml file” for more information.

Creating your tc-driver.xml file
The manifest file for an automation package is an XML file that contains the name and the version
number of the automation package, the version number of the automation package template, and
describes all of the driver’s dependencies on other automation packages. The manifest file must include
the following main sections:
<dependencies>
This section lists all of the other drivers the current automation package depends on.
<actions>
This section lists all of the separate classes that are necessary to install separate items like Java
drivers, commands, and so on.
<items>
This section lists all the items to be installed on the automation package. Each item identifies a
certain operation that will be performed on that automation package.
<device-models>
This section lists all the items to be installed on the automation package. Each item identifies a
certain operation that will be performed on that automation package.
<post-install-workflows>
This optional section names a workflow along with its parameters to run after all the items are
installed. This workflow could be one that was installed by the current automation package, or
one that had been previously installed.
<property>
This optional section defines a macro substitution that can be used for any strings that are
referred to in the manifest file. For example, if we have the following entry:
<property name="tc.pkg"location="com.thinkdynamics.kanaha.tcdrivermanager.action"/>

then, wherever ${tc.pkg} occurs in an attribute string inside tc-driver.xml, a substitution is made.
<software-products>
This section defines any software product entries to install in the data center model database. The
syntax is identical to the <software> element in the XML format used by the xmlimport utility,
but has been extended to allow for ${xxx}property substitutions within attribute values.
<driver-name>
Name of the driver. This name must exactly match the name of the automation package.
<driver-version>
The version number (optional).
<description>
Describes the purpose of the automation package.
<documentation>
Specifies the name of an html file in the automation package that provides a description of the
automation package as well as installation and troubleshooting details.
The order of items in your XML file
The order that the <items> are listed in your XML file is very important and needs to follow a specific
pattern. This pattern reflects the order that each item will be installed and uninstalled. Flat files are
Chapter 18. Creating an automation package

49

installed first, followed by Java plug-ins, and workflows. The uninstall of the automation package follows
a reverse order: workflows are uninstalled first, followed by Java plug-ins, and all flat files.
<items>
<item name="Flat files (for example, shell scripts)">
</item>
<item name="Java plug-ins">
</item>
<item name="Workflows">
</item>
</items>

Naming your XML file
The name of your XML manifest file must be named: tc-driver.xml.
Sample tc-driver.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<tc-driver>
<tc-driver-format>1.0</tc-driver-format>
<driver-name>Oracle9i</driver-name>
<version>1.0</version>
<dependencies>
<dependency name="Core"/>
</dependencies>
<property name="tc.pkg" location="com.thinkdynamics.kanaha.tcdrivermanager.action"/>
<actions>
<action name="copy-file" class="${tc.pkg}.CopyFileActions"/>
<action name="driver" class="${tc.pkg}.DriverTypeActions"/>
<action name="workflow" class="${tc.pkg}.TxtWorkflowAction"/>
</actions>
<items>
<item name="repository/uninstall.oracle9i.sh" action="copy-file">
<param name="dest.path" value="${tc.home}/repository/oracle/uninstall.oracle9i.sh"/>
<param name="chmod" value="755"/>
</item>
<item name="workflow/Test Uninstall Oracle 9i.wkf" action="workflow" />
</items>
<device-models>
<device-model name="Oracle 9i install" category="Software Products">
<workflow name="Test Uninstall Oracle 9i"/>
</device-model>
</device-models>
<!-<post-install-workflow name="workflow name">
<param name="command variable name" value="value>
</post-install-workflow>
-->
</tc-driver>

Creating automation package documentation
Formally known as readme.txt, an html file needs to be created that includes the details associated with
installing your automation package.
1. Create the documentation for your automation package. Refer to the sample below for details on what
information needs to be included.
2. Save the file with a name that matches the name of your automation package: tcdriver_name.html. For
example, if your automation package is called extreme-48i.tcdriver, your html should be named:
extreme-48i.html.
For more information on what should be included in each section of the automation_package_name.html
file, refer to the template provided.
Related information

50

Workflow Developer’s Guide

Automation packages
Automation packages are single packages with a .tcdriver file extension that contain all of the
workflows, database table entries, JAR files, and external scripts that are necessary to operate a
physical device, such as a Cisco CSS11000 switch. They represent a logical grouping of entities that
together provide a complete solution for a specific device driver. All automation packages are located
in the $TC_HOME/drivers directory on the Tivoli Intelligent ThinkDynamic Orchestrator or Tivoli
Provisioning Manager server. By using automation packages, you can assemble the full suite of logical
operations and associate all the behavior of a device-model into one unit.
Automation package manager
Automation package manager is a utility that manages automation packages . It requires a
configuration file, $TC_HOME/config/tcdrivermanager.xml, that defines the location of the directory
holding the drivers, and any other properties definitions that are common to all automation packages.
It also uses the dcm.xml and objectview.prop files for database connection information. The
automation package manager can run independently from any other Tivoli Intelligent ThinkDynamic
Orchestrator engines.

Chapter 18. Creating an automation package

51

Sponsor Documents

Or use your account on DocShare.tips

Hide

Forgot your password?

Or register your new account on DocShare.tips

Hide

Lost your password? Please enter your email address. You will receive a link to create a new password.

Back to log-in

Close