3

Chapter

Basic Concepts
Nodes, Links and Directed Acyclic Graphs
A metaController application is assembled of a set of nodes linked together in a
directed acyclic graph (DAG). A node represents an atomic process which is executed
as a unit. The DAG defines a dependency graph, which can be expressed as: in order
to execute a node all its predecessors must be executed. The possible statuses of a
node are: NOTREACHED, READY2GO, INPROCESS, COMPLETED,
ERROR, CACHED, and PSEUDO-COMPLETED.

Nodes without a predecessor are called start nodes, and nodes without a successor
are called end nodes. The metaController initially schedules for execution the set of
start nodes since these have no predecessors.

Regular links (also called links hereafter) establish the predecessor → successor
relationship. Error links (displayed in red and dashed) are only followed when the
status of the source node is ERROR, and in this case the regular links are not
followed.

NOTREACHED is the status of a node that can not be considered for execution; its
color code is transparent. READY2GO is the status of a node that satisfies the
condition to be activated and its color code is blue. INPROCESS is the status of a
node started for execution (an external process has been spawned), and its color code
is yellow. COMPLETED is the status of a node whose execution completed
normally; its color code is green. ERROR is the status of a node whose execution
completed with an error condition; its color code is red. For a description of the
CACHED and PSEUDO-COMPLETED statuses, see the Advanced Topics
section.

metaController User Guide 31

 Figure 2 A sample flow with nodes and regular links

Basic Usage
The metaController Client component allows a user to create process flows in
separate windows, save them as XML files, or as runnable processes in the
metaController repository. Flow designers could work on portions of a larger flow off

metaController User Guide 32

 line, share the XML files with other designers, merge the XML files together and
finally save the resulting process to the workflow engine repository for execution.

Edit Mode. Assembling a Flow

When you start the metaController client, an empty window is created and you can
start assembling a process flow. This input mode is called Edit Mode.

Creating a Node
Drag and Drop Drag a node from the metaController palette and drop it to the
active document.

Click Once Click once on a node in the palette and click again in the
document.

Double Click Double click on a node in the palette and click a number of times
in the active document to create as many nodes. To deselect the
“multiple drop” mode, click anywhere in any palette.

Creating a Link
Click Once Click once on a link in the palette and then click the source node
first and the target node second.

Double Click Double click on a link in the palette and then click a number of
times in the active document first on the source node and then
on the destination node. . To deselect the “multiple drop” mode,
click anywhere in any palette.

Selecting an Object
Click on the object. The object inspector (if open) will display all object attributes. To
select multiple nodes, hold down the Shift key and click the additional object. Or,
select all objects in a rectangle by holding down the right mouse button while
dragging it around.

Grouping a Set of Nodes / Ungrouping a Group

Select the nodes to be grouped and click the Group button on the tool bar. Select the
group to be ungrouped and click the Ungroup button on the tool bar.

Saving to / Reading from an XML File

Once you have a flow schema in the active window and you want to save it to a file,
click the Save or Save As buttons on the tool bar. You will be prompted to specify a
file name.

To read a flow from a file, just click the Open button on the tool bar and select the
file.

Logging into the metaController Repository

In order to log in into the metaController repository click the Login button on the
toolbar. The Login window is displayed and you can enter the authentication

metaController User Guide 33

 information. A metaController client can establish connections to multiple
metaController servers, and as different users.

When the user authentication fails or another problem occurs, an error message is
displayed at the bottom of the window. The message disappears as soon as the user
modifies any of the window fields.

Figure 3 The Login Window.

Server URL The server DNS name or IP address along with the port number
separated by colon (“:”). For example, zeus:8001.

User Name The name of the metaController user.

Password The password of the user name entered above.

Login Initiates the authentication process. Disabled if any of the fields

is empty.

Close Cancels the operation.

Managing Process Flows

Process flows stored in the repository are organized into domains and versions.
Examples of domains include the Development domain (DEV), the Production
domain (PRD), or even private domains for individual developers. Security (what
rights a logged in user has) is defined at the domain level. Within a domain, when
process flows need to be modified, a new version is usually created. This allows the
administrator to upgrade a process flow while an instance of the old flow is active in
the repository. By creating a new version of the flow, the old version is preserved for
historical and audit reasons. As a caveat, the new version of the process flow will start
execution immediately, and one needs to take some precautions against the new
process from stepping on the old one.

While designing and testing, one can overwrite the existing process flow (save over an
existing flow). If there is a structural change in the new flow as compared to the old
flow, metaController will delete the event and message logs. As a result, in a
production domain we do not recommend saving over an existing flow, unless there
is no structural change in the flow or the run history is not relevant.

metaController User Guide 34

The Select Domain & Version window will pop up whenever the user attempts to (1)
save a flow to the repository; (2) retrieve an existing flow from the repository, or (3)
monitor the execution of a flow stored in the repository. If the user has not been
authenticated to access the metaController repository the Login window is opened
automatically.

The Select Domain & Version window contains all metaController repository
authenticated connections, for each connection all available domains, and for each
domain, all versions.

Figure 4: The Select Domain & Version window

The Select Domain & Version window allows the user to select a process from the
tree and either open it or remove it from the repository. The user also has the option
to lock the flow to open such that other users cannot access it for modification
concurrently.

When none of the existing repository connections contains the desired flow due to
authentication reasons, the user can create a new connection with the right credentials
by clicking the Add Server button. This will re-populate the tree including the new
repository connection node.

metaController User Guide 35

 Domain Tree A tree is created for each of the repository connections with the
following structure: level 1: Root Node – Logged in Users; level
2: Opened repository connections [serverUrl:port/userName];
level 3: Domain name; level 4: Version name

Remove Deletes a flow from the repository. Disabled when the selected
tree node is not a flow.

Add Server Allows logging in as a new user and getting the domains and
versions for that user. Displays the login window and recreates
the tree.

Version Name When a version node is selected, this field contains the version
name for that node; otherwise it is blank.

Description When a user selects a version node, this field contains the version
description for that node; otherwise it is blank.

Lock Process Allows locking of the process to be opened so that other users
cannot access that process.

Ok Completes the selection of a process flow. This button is

disabled when the node is not a process. If a process is already
open then results in the “Refresh Window” pop-up.

Close Cancels the operation.

Read from / Save to the Repository

To read a flow schema from the repository into the active window, click the Read
from Repository button on the toolbar. You will be prompted to log in into the
metaController server (if not already logged in), and then specify which flow to read
(domain and version).

Once you have a flow schema in the active window and you want to save it to the
database for processing, click the Save to Repository button on the tool bar. You will
be prompted to specify a domain and version where you want the flow to be saved.

If the selected version already is opened in a client window the Open Process Action
Option window allows you to open the process in a new window or in an existing
window. Multiple instances of the same flow are distinguished by the instance
number (in square parentheses).

metaController User Guide 36

 Figure 5: The Open Process Action window

New Window Creates a new window for the selected flow.

Refresh Window Retrieves data from the database and redraws the selected
window.

Existing windows Titles of existing windows opened for the selected process. The
selected window is redrawn from the retrieved data from the
repository.

Ok Creates or refreshes a window.

Cancel Closes the window without creating or refreshing a window.

Monitor Mode
Monitoring Execution
Once a flow saved to the database is in the active window, you can monitor its
execution by clicking the Monitor button. This will receive all status changes for the
specified flow from the server as they occur and will display them color coded.
NOTREACHED is coded as transparent, READY2GO is coded as blue,
INPROCESS is coded as yellow, COMPLETED is coded as green, ERROR is
coded as red, CACHED is coded as magenta, and INPROCESS with “execution
exceeded historical limits” warning as orange.

In monitor mode, you have the option to display the execution log window. The
execution log window displays information about the execution of processes,
including start and end time.

To deactivate monitor mode, click the Monitor button again.

Examining the Execution Log

The Execution Log window displays the execution log for the flow in the active
window, provided that it is in Monitor mode. The information is displayed according
to the user’s preferences.

metaController User Guide 37

Figure 6. The Execution Log window.

Status The node status. Displayed as icons – Information / Warning /

Error.

RID Run time process Id.

NST Instance number.

CID Compile time process Id.

PID Process Id.

Time Time of the event.

Message Description of the event.

Level the severity level of the event.

Log Options window

The user can specify attributes for the Execution Log window using the Log Options
window. The input values are stored on the local machine in an xml file.

metaController User Guide 38

 Figure 7: The Log Options window

System Time Select the log rows generated after that date and time.

Asc/Desc Sort the rows in ascending or descending order by the Time

column.

Show verbosity Severity level equal to or higher than the value selected. A user
can select values between 1 and 10.

Show Rows Number of rows to be displayed in the log table.

Show Client Log When this option is checked then only the client side log is
displayed.

Show Server Log When this option is checked then only the server side log is
displayed.

Ok Commits the changes to the XML file.

Close Closes window without saving any data to the XML file.

Standard Activity Attributes

Each node has a set of attributes which correspond to the process parameters. The
most important attribute is the type of process. Examples of process types are:
FILEWATCH, ORACLEEXEC, ESSDIMBUILD. See the Reference section for a
complete description of all available processes.

Design Time Attributes

The design time attributes exposed by all metaController nodes are:

active Y/N – specifies if the node is active or not; an inactive node

is not executed, but its status is changed to COMPLETED
immediately.

metaController User Guide 39

 boundary Y/N – if set to Y, this node is a boundary node (see the
Boundary Nodes paragraph in the Advanced Topics
section).

err_handler the name of an Error Handler node that represents the start
of an error handler flow. See the Error Handling paragraph
in the Advanced Topics section.

err_handler_type handle or raise. See the Error Handling paragraph in

the Advanced Topics section.

hold Y/N – a value of Y will cause the node to not transition

from READY2GO to INPROCESS; changing its value in
Monitor Mode to N (via the right click Process RELEASE
action – see the Advanced Topics section) will result in the
node transitioning to INPROCESS status immediately.

name The name of the node, mostly used to distinguish it from

other nodes of the same type.

restartable Y/N – a value of Y specifies that in case the server crashes in

the middle of execution of this node, on startup the server
could safely restart the process; if the value is N then the
server will not restart the process and human intervention is
needed.

warn A ‘double’ number that specifies the amount of time to

elapse before the node is flagged with an "Execution Time
Exceeded Historical Limits" warning message. The
“historical limit” value is the historical average execution time
of the node. The interval before the warning message is
computed by multiplying the average execution time with the
warn value. The default value for the ‘warn’ attribute
depends on the node type.

Run Time Attributes

In monitor mode, a node displays an additional set of run time attributes which
communicate status and other type of run time information about the process.

end the time and date when the node was last COMPLETEd.

err if the status of the node is ERROR then this attribute contains a
relevant error message.

start the time and date when the node execution was started.

status the current status of the node.

metaController User Guide 40

Run Time Attributed Useful in Debugging
These attributes are hidden by default. You can un-hide them by modifying the
common file in the bin directory.

blocked the run number of the blocked process.

color the graph is colored such that all connected nodes have the same
color.

run the run number of the current node execution.

section the set of boundary nodes define sections of nodes that can not
have overlapping runs (see the paragraph on boundary nodes in
the Advanced Topics section).

Link Attributes
Each link has a set of attributes which specify particular behavior for the link.

condition always/value – always specifies that the link is

always followed; value specifies that the link is only
followed if the parameter value $value$ is in the
condition_op relationship with condition_val.

condition_op if condition is value then one of: =, !=, <=, >=, <, >

condition_val if condition is value then a double.

on_cached Y/N – a value of Y specifies that if the status of a

predecessor node is CACHED it is considered to be
COMPLETED for starting successor nodes purposes. If the
value is N then CACHED is not equivalent to
COMPLETED for starting successor nodes purposes. See
the paragraph on Processes with Different Periodicities in
the Advanced Topics section.

pass_info Y/N – is used only for File nodes; a value of Y specifies that
the file name specified in this node is used in a successor
node via this link. A value of N specifies that the file
specified in this node is not used in the successor node.

The error link has only one attribute,

on_err_handled COMPLETED/READY2GO – specifies the restart status

of the target node after the error handling flow has been
completed (see the Error Handling paragraph in the
Advanced Topics section).

metaController User Guide 41

Parameters
The values of activity attributes can be hard coded or computed at run time using one
or more PARAMS nodes. One would hard code an attribute when the value does not
change (is a constant known at flow save time), is the same on all flow environments
(such as Development, UAT, Production), or for testing. One would compute the
attribute values at run time when it changes from environment to environment,
changes in time triggered by external events, or is comprised of multiple components
that are retrieved separately. To enter a constant value just type it in the attribute edit
box. To specify a variable, use the special construct <%=param%>, where param is
the name of a parameter generated by a prior PARAMS node. Parameters are
available to all nodes that follow the node that generated them, not only to the first
node that follows the PARAMS node. Multiple PARAMS node can contribute to the
attributes of a single node, even to the same attribute of a single node.

When evaluating a PARAMS node, one or more (name, value) pairs are
generated. metaController parses most activity attributes and attempts to substitute
the variable construct <%=name%> with value. If multiple PARAM nodes
generate multiple parameters with the same name, the substituted value is the one
generated last. As a result, if two PARAMS nodes link to the same node and they
generate the same parameter then the substituted value is not deterministic.

metaController User Guide 42

 Figure 8. Multiple PARAMS node feeding one process node.

In figure 8, assume node [1] generates parameters (p11, v11), (p12, v12), (q, v13);
node [2] generates (p21, v21), (p22, v22), (r, v24); and node [3] generates (p31, v31),
(p32, v32), (q, v33), (r, v34). The following (name, value) pairs are available to node
Essbase Dim Build: (p11, v11), (p12, v12), (p21, v21), (p22, v22), (p31, v31), (p32,
v32). Also, either (q, v13) or (q, v33) depending on the order in which the parameters
have been generated. Finally, (r, v34) because this value has been generated before (r,
v24). Assuming the value of attribute attrib of node Essbase Dim Build is
<%=q%>.<%=r%>, then it will be expanded at run time to either v13.v34 or
v33.v34.

Named Resources

metaController User Guide 43

 The types of resources that can be defined in metaController are data sources and
message sources. A data source wraps a database connection and a message source
wraps a JMS connection. A named resource associates a name with all the
information needed to establish the connection. Both loose resources and pooled
resources can be defined in metaController.

A loose connection is built on the fly using the information in the resource. After
usage, it is destroyed. A pooled of connections is built when the metaController
server starts.

Pools of resources are used for performance reasons. Instead of creating a resource,
using it for a specific purpose and then destroying it, one can define a pool of
resources that are acquired, used, and released. The performance gain is due to the
fact that the ‘create’ and ‘destroy’ operations are usually more computationally
intensive than the ‘acquire’ and ‘release’ operations.

Resources are defined using the metaController Admin utility.

metaController built-in processes that use named resources have an attribute named
datasource that contains the name of the resource to be used. For example, in
the case of the Stored Procedure processor, the datasource attribute specifies the
database and credentials used to execute the stored procedure.

Data Sources

A data source is fully defined by the following set of attributes: User Id, Password,
JDBC URL, JDBC Driver, and Database Vendor. There is a built-in datasource that
points to the metaController repository. Its name is TEAMC and select attributes can
be further configured after the initial installation.

Message Sources

A message source is fully defined by the following set of attributes: JNDI User Id,
JNDI Password, JNDI Initial Context Factory, JMS Factory, JMS Queue Name, and
JMS URL.

Remote File Operations - Secure Shell Details

metaController provides two types of File Operation nodes – local and remote. A
local file operation node accesses the file(s) on the local machine. A remote file
operation node accesses the file(s) on a remote machine using the Secured Shell
protocol (SSH), which connects to the remote machine using encrypted and secured
authentication. Authentication is done using a valid account in the remote operating
system (Windows, UNIX, etc.). For remote file operations, metaController supports

metaController User Guide 44

 Key and Password based authentication. The authentication method is specified in
the authentication attribute of all remote file operation nodes.

Password Based Authentication

During password based authentication, metaController supplies a user id and
password when connecting to a server specified by either a DNS name or an IP
address. The remote file operation node retrieves this information based on the
alias attribute present in all remote file operation nodes. The administrator
associates the alias name with the server and credential information in the OS Users
module of the Administration utility (see the metaController Administration Tool
section for more information).

Key Based Authentication

During key based authentication, metaController supplies a user id and a private key
when connecting to a server specified by either a DNS name or an IP address. The
remote file operation node retrieves the user and server information based on the
alias attribute present in all remote file operation nodes. The private key is
retrieved from the private key file obtained using the SSH key generation utility. The
location of the key file is specified in the
TEAAgent.fileWatch.sshkeyfile tag in the configuration file
teamc.xml. The default value for the
TEAAgent.fileWatch.sshkeyfile tag is sftpkey, and its default
location is <MC_HOME>/tea/mc/bin.

metaController User Guide 45

 4
Chapter

Advanced Topics
Grouping
Grouping allows the logical gathering of processes into larger grain processes. The
goal of grouping is to decrease complexity while allowing drill down to the
component process level.

Groups can be in turn grouped at a higher level; there is no limitation as to the

number of nested groups allowed.

Within a group, all nodes without a predecessor are considered start nodes and all
nodes without a successor are considered end nodes. If a link connects a node and a
group, behind the scenes the node is connected to all start nodes of the group. If a
link connects a group and a node, behind the scenes all end nodes of the group are
connected to the node. If a link connects group 1 with group 2, behind the scenes all
end nodes of group 1 are connected to all start nodes of group 2. The attributes of
the generated links are the same as those of the original, group links.

The type attribute of a Group node is SUBFLOW.

To group a set of nodes, just select all the nodes you want included in the group and
click the Group button in the metaController Editions tool bar.

metaController User Guide 46

Figure 8: Groups and group links

metaController User Guide 47

Modifying the active Attribute for All Successors of a Node
In order to skip the execution of a node process without removing the node from the
process flow, one can modify the active attribute of the node to N. This way the
status of the node transitions immediately from READY2GO to COMPLETED.

In order to inactivate all successors of a node, but not the node itself, in Edit Mode
modify the action_successors attribute of the node.

Stopping / Resuming the Execution of a Node

In order to suspend the execution of a process at a specific node, one has to set the
hold attribute of the node to N. This can be accomplished in Edit Mode by
modifying the attribute and saving the flow to the database, or in Monitor Mode by
setting the action_process attribute to HOLD. In turn, this will set the hold
attribute for the node to Y and save the value to the database. As a result, when
control reaches that node the transition from READY2GO to INPROCESS is
stopped.

To resume a stopped process, in Edit Mode one can modify the hold attribute value
to N and save the process flow to the database; or in Monitor Mode modify the
action_process attribute to RELEASE.

Correcting Execution Problems

When an execution error occurs and no error handling link has that node as a source,
the error can be corrected manually. The object inspector has an attribute called
action_restart which allows (only in monitor mode) to adjust the status of the
selected node. In turn, this will allow executing the node again or skipping it
(considering it COMPLETED).

In the above scenario, the status of the node was ERROR. It is possible that a
process just crashes and does not set the status to ERROR; in fact the status just
remains INPROCESS. For example, it is possible that a File Watch process is waiting
for a file that the user just knows will never appear. In this case the process
administrator can still adjust the status to resume the process in two steps, as
discussed below.

Finally, a process can not only be restarted from the failure node, but also from a
previous node. The condition is that none of the successor nodes (via transitive
closure) is INPROCESS.

The possible values of the attribute are COMPLETED, READY2GO, and ERROR.
The COMPLETED value will set the status of the node to completed and will thus
allow subsequent nodes to continue. Make sure the data provided by the process is
available before adjusting the status, otherwise errors could be reported in subsequent
processes. The READY2GO value will simply restart the execution of the node; it is

metaController User Guide 48

 assumed the user has fixed the problem that has caused the error in the first place
otherwise the error will occur again.

If the status of a node is INPROCESS but the administrator knows that the actual
status is ERROR or the node operation needs to be canceled, he can adjust the status
to ERROR by selecting action_restart to ERROR. Subsequently, he can
change the status again to READY2GO of COMPLETED.

Finally, note the restrictions associated with the recovery action: (1) the allowed
transitions are from status ERROR to READY2GO or COMPLETED, from
COMPLETED to READY2GO, and from INPROCESS to ERROR; (2) at the
time of the COMPLETED to READY2GO transition none of successors of the
recovered node must be INPROCESS; (3) the recovered node must be in the same
section with the error node; (4) the recovered node must not be a direct or indirect
successor of the error node.

Advanced Nodes (Boundary Nodes)

Overlapping Runs
Without boundary nodes, a process flow is executed start to finish being assigned
what is called a run number. When the last node is completed, the process starts anew
with a new run number.

Boundary nodes allow multiple runs of the same flow to overlap. The set of all
boundary nodes define sections within which only one run is active. To change a
regular node to a boundary node, just change its commit attribute to Y. Make sure
that the set of boundary nodes define the intended sections (inspect the section
run time attribute of the process nodes). A boundary node is differentiated visually by
its circular shape (as opposed to the square shape of regular nodes).

When boundary node n1 is reached for run r1, metaController examines the section
that follows n1. If there are active nodes in that section (with run number r2) then
the r1 run is blocked at node n1, and its status becomes CACHED (color code
magenta). The execution of node n1 with run number r1 will be resumed as soon as
the section with run number r2 becomes inactive.

When are boundary nodes useful?

Consider the case when a file is loaded into a database table and then the data is
processed via a stored procedure that runs for a considerable amount of time,
ultimately storing the end results in work tables. The next process is another stored
procedure that moves the data from the work tables into cache tables, where they are
used by subsequent processes.

If the next file is available while the subsequent processes are still running, without
boundary nodes one would have to wait until the subsequent processes are
completed, and then wait until the data is processed in the work tables. By defining
the move stored procedure node as a boundary node, the loading of the next file and

metaController User Guide 49

 the processing can safely be executed while the previous run is executing the
subsequent processes.

Figure 3 depicts the execution of example ex02, in which nodes 20, 23, and 24 are
boundary nodes and define four sections. Section 1 comprises nodes 1, 18, and 19;
section 2 comprises nodes 20, 21, and 22; section 3 comprises nodes 23, 25, 26, 29,
and 30; and section 4 comprises nodes 24, 27, 28, 30, and 31. Notice that node 30
belongs to both sections 3 and 4. As a result, when node 23 was unblocked, its
section was cleared and node 24 could no longer be unblocked, although initially both
sections 3 and 4 were candidates for clearing.

Figure 9: Overlapping process runs

Executing Processes with Different Periodicities

The setting of the on_cached property of a link only makes sense if the source node
is a boundary node, because non boundary nodes never get their status set to
CACHED. Setting this property to Y (the default value) ensures that a CACHED
value for the status of the boundary node is equivalent to COMPLETED for the
successor node. In other words, if all the predecessor nodes of a node are either
COMPLETED; or they are linked with the node via links with the on_cached
attribute set to Y and their status is CACHED, then the node can be executed.

This allows processes with different periodicities to be executed. For example,

consider a monthly and a daily process. The monthly process loads a file into a table
every month and the daily process loads another file into another table. Subsequently,
the daily table is processed by joining it with the monthly table.

metaController User Guide 50

 Figure 4 depicts the execution of a process with two different periodicities (example
ex23). The daily process on the left (nodes 220, 9, 93, and 91) has just used the cached
value on node 92, so the status of node 93 just changed to COMPLETED. Node 92
belongs to the monthly process (nodes 221, 94, 92, and 95). Node 94 simulates a file
watch for the monthly file.

Figure 10: Processes with two different periodicities

Advanced Links (Conditional Execution)

Conditional links are implemented using the condition, condition_op, and
condition_val attributes of regular links.

The condition attribute must evaluate to value, the condition_op must evaluate to
one of =, !=, <=, >=, <, or >, and condition_val must evaluate to a double. The

metaController User Guide 51

parameter named $value$ is searched in the list of parameters available to the node
and the appropriate operation is executed. If the result of the comparison is true then
the link is followed, and the successor node is started. If the result is false then the
link is not followed, but the status of the successor node is set to PSEUDO-
COMPLETED (color code gray), which is always equivalent for the purpose of node
execution starting to COMPLETED.

The $value$ parameter can be created either via the Parameters node or the Oracle
Procedure node (with one return value).

Example 25 illustrates the usage of conditional execution (example 25). Node 94

executes an Oracle stored procedure with one return value (indicated by the ‘?’). The
random value is checked against the conditional logic and only node 92 is executed.
Node 96 is placed in a PSEUDO-COMPLETED status, such that node 93 can be
started when nodes 92 and 9 are both completed. The example conditional logic
contains mutually exclusive conditions for the links connecting node 94 with nodes
92 and 96 such that at any given moment only one branch is followed. Notice that
node 95 is always executed since the link connecting the two nodes is not a
conditional link.

metaController User Guide 52

 Figure 11: Conditional execution

Subroutine Execution
Subroutine flows are sub-flows that are defined once and are invoked (concurrently)
many times from different places, similar to subroutine constructs in traditional
programming languages. Invocation of a subroutine flow is accomplished via a
SUBCALL node. The example in Figure 12 contains two subroutine flows
(FILECOLLECTION and FILEMOVE), and three SUBCALL nodes (two nodes in
the main flow - [12] Product Information and [22] Customer Information – and one
in a subroutine flow – [102] Designated 2 History).

When a SUBCALL node is executed, its sql attribute is interpreted as an SQL

statement and evaluated. It must return a result set with a column named ‘sub.’
Alternatively, the sub attribute of the SUBCALL node can contain one SUB flow

metaController User Guide 53

name. In this latter case, no parameters are transferred to the sub flow. If the routine
set (provided by evaluating the sub and sql attributes) is empty then based on the
value of attribute failOnNone the node will change status to ERROR (for Y) or
COMPLETED (for N).

The sql attribute of node [12] in Figure 12 contains:

SELECT 'FILECOLLECTION' AS sub, FILE_NAME FROM

FILECOLLECTION WHERE FILE_GROUP = 'Product
Information'

For all records in the result set, one subroutine instance is generated and its execution
started. The value of the sub column is used to identify the subroutine flow to be
invoked, and all the other columns are passed as parameters to the invoked routine.
Assuming the above SQL statement returns two records, subroutine
FILECOLLECTION is invoked two times. Each invocation is passed one
parameter, FILE_NAME. Therefore, in any node of the FILECOLLECTION
subroutine we can use the parameter construct <%=FILE_NAME%>. In this
example, the parameter is used in node [102] (SUBCALL) in its sql attribute:

SELECT 'FILEMOVE' AS sub, '<%=FILE_NAME%>' AS

file_name FROM DUAL

Subroutine FILECOLLECTION thus in turn invokes subroutine FILEMOVE

passing it a parameter named also file_name, with the value that it was invoked with.

A subroutine flow is just a top level Group node (see the section of Groups above)
with a non empty sql attribute. You can thus define a subroutine flow by selecting the
nodes to be included in the subroutine flow, clicking the Group button, and entering
a SQL statement in the Group sql attribute. Unlike top level groups which are
executed as independent flows, subroutine flows are only executed via SUBCALL
constructs.

The sql attribute of a subroutine flow node is used to get additional parameters for
the execution of the routine. It is processed as the column based sql attribute of a
PARAM node. In the example in Figure 12, the sql attribute of the
FILECOLLECTION subroutine contains:

SELECT FILE_GROUP, DESIGNATED_DIR, HISTORY_DIR,

SOURCE_DIR, TARGET_FILE_NAME, to_number(eta_to-
eta_from)*24*60*60+60 AS TIMEOUT FROM FILECOLLECTION
WHERE file_name = '<%=FILE_NAME%>'

which creates six parameters and makes them available to successor nodes
(FILE_GROUP, DESIGNATED_DIR, HISTORY_DIR, SOURCE_DIR,
TARGET_FILE_NAME, TIMEOUT).

metaController User Guide 54

All parameters accessible to the SUBCALL node are accessible to all nodes within the
body of the called SUBs.

Figure 12: Subroutine processes

metaController User Guide 55

Error Handling
By default, when a node execution results in an error condition, metaController (1)
changes the status of the node to ERROR and updates attribute err with the text of
the error message, (2) displays the error message in the log window, (3) sends a
standard e-mail notification to a set of recipients defined via the TEAAdmin utility.
When the status of a node is ERROR, an administrator has the option to correct the
error, as discussed in the section titled “Correcting Execution Problems.”

In order to automate the error handling process, metaController allows the definition
of Error Handling flows. In order for an error handling flow to be invoked in case an
error occurs while executing a node, its name must be specified as the
err_handler attribute of the node. In the example in Figure 13, the
err_handler attribute of node [12] is myErrorHandler, which is the same as
the name attribute of the error handling flow (group node). metaController allows
two error recovery strategies: (1) via return codes – see Figure 13, and (2) via recover
actions – see Figure 14.

All parameters accessible to the node reporting the error are accessible to all nodes
within the body of the error handling routine.

From a node perspective, an error handling flow, like a subroutine flow, is a top level
Group but with a non empty return attribute as opposed to non empty sql
attribute.

Error Handling via Return Codes

If there are no error links originating from the node where the error occurred (call it
the error node), the return attribute specified in the error handling flow is made
available to the error node as the system parameter $value$. In turn, this
parameter can be used to follow conditional links as discussed in section Advanced
Links above.

In the example in Figure 13, the logic is as follows: if there is an error in the node 12,
execute the myErrorHandler error handling flow which will log the error
message in a table, then set the status of node [13] to COMPLETED, and continue
with node [14]. If there is no error, continue with node [13]. This way, the main flow
(starting with node [11]) can be re-executed without human intervention and the error
condition logged.

After executing the error handling sub flow, metaController allows two continuations:
(1) assuming that the error handling sub flow has fixed the error, the main flow can
continue (this is the scenario discussed above); (2) the error handling sub flow has
only executed some actions that have not fixed the problem (e.g., has only sent e-mail
to the sys admin) and hence the main flow cannot continue. In this latter case, the
status of node [13] remains ERROR and neither node [13] or [14] are executed.

metaController User Guide 56

 In order to accomplish continuation (2) above, the value of attribute
‘err_handler_type’ must be ‘raise.’ The default value of this attribute is ‘handle’
and corresponds to continuation (1).

Figure 13: Error handling via return values

Error Handling via Recovery Actions

In some instances, simply ignoring the error condition may not suffice. A file may
need to be restored and the execution may need to be restarted, possibly from a prior
node. Such logic is implemented via error links (red, dashed lines).

If there is at least one error link originating from the node with the error, the error
handling flow return code is not made available to the error node. Instead, when
control passes back to the error node, all error links are followed and the recovery
action specified on the link is executed. This behavior simply automates the recovery
options available to the administrator from the GUI level in Monitor mode (see the

metaController User Guide 57

Section titled “Correcting Execution Problems” above). Note that unlike the manual
recovery actions which is applied to one node at a time, the automated actions can be
applied to multiple nodes (all nodes reached vie error links from the error node).

Note also that the restrictions associated to the recovery actions still apply to the
automated recovery actions. In addition, one cannot have an error link from a node
in a section to a subsequent node, or to a node in a prior section (defined by
boundary nodes). This latter restriction is because a previous section may be active,
and therefore the flow instance being corrected may interfere with a more recent
instance.

Finally, note that if a node is the origin of an error link, then if an error occurs within
that node, the recovery action will be executed regardless whether an error handling
flow is associated to the node itself or not.

Notice that in the case of error handling via recovery actions, the value of attribute
‘err_handler_type’ is irrelevant, as the error links are always followed.

Figure 144: Error handling via recovery actions

metaController User Guide 58

Process Playback
Monitoring allows an administrator to examine the execution of a process flow as it
happens, and recover from process errors. Process Playback allows the administrator
to observe the historical execution of a process one event at a time or compressed;
one step at a time or continuous; search for the next error condition; forwards or
backwards. To use the Playback feature, you need to be in Edit Mode. Click the
Playback button on the client toolbar and the Playback console will pop up.

Figure 15: The Playback console

In Normal (uniform) Sampling mode, the execution of the process is re-played by

sampling the flow status at constant intervals. The execution starts at the Start Time
input by the user and is sampled every “Sampling Interval” seconds. The status of the
process at that time is displayed. Intermediate statuses may be missed, but the
playback resembles the actual execution with respect to execution speed.

In Compressed Sampling mode, if the Compressed Window value is 0, all the events
that occur at the same time are lumped together, the status is displayed for a period of
“Display Interval” seconds, and then the next set of events is considered. Since
Oracle stores time in increments of one second, many events may be lumped
together. If the Compressed Window value is greater than 0, the execution of the
flow starts at the Start Time value input by the user, and all events that have occurred
between the Start Time and Start Time + Compression Window are lumped together
and the latest status is displayed. Next, the time is advanced to the time of the next
event after Start Time + Compression Window and the status of the flow at that time
is displayed. The playback continues in the same manner.

The interval between two consecutive status updates is the one selected in the Display
Interval box.

Start time Start time (yyyy-mm-dd hh:mm:ss.ms format i.e., 2003-04-

15 12:15:00.0)

metaController User Guide 59

End time End time (yyyy-mm-dd hh:mm:ss.ms format i.e., 2003-04-
15 12:30:00.0)

Compressed Sampling Normal / Compressed mode playback. See the

description.

Sampling Interval / Compression Window See the description.

Display Interval Time in seconds to display the flow status before

advancing to the next status.

Currently Playing The current execution time.

Playback buttons:

Skip backward until the next error is encountered.

Step backward.

Play the process execution backward.

Play the process execution forward.

Pause the process execution.

Stop the process execution.

Step forward.

Skip forward until the next error is encountered.

metaController User Guide 60

 5
Chapter

Reference – metaController
Automation Services
File Processes
File Watch
Description
A File Watch node is an agent process that completes when a file is detected on the
agent machine with the name and in the directory specified in its attributes. The node
could also report an error condition if the timeout interval has been exhausted and
the file has not appeared.

Attributes
agent the alias of the agent that runs this process

Example: localAgent

file the full path name of the file that is being watched

Example: c:\Program Files\tea\samples\03\emp1.dat

seq integer - this attribute is not used by the File Watch node itself.
Successor nodes (like File Concatenate) use the seq value to
define the order in which the files are being used (i.e.,
concatenated).

timeout integer - a value of -1 indicates that metaController waits

indefinitely for the file to appear at the specified file location
on the agent machine. A positive value specifies that
metaController should wait at least that many seconds before
reporting an error.

File Copy
Description
A File Copy node is an agent process that makes a copy of a predecessor file to a
different location, on the same agent machine. The location of the predecessor file is

metaController User Guide 61

 the file attribute of a predecessor File node (Watch, Copy, Move, Concatenate, or
Essbase). If multiple File nodes precede this node, only the first is copied; the rest are
ignored.

Attributes
agent the alias of the agent that runs this process;

Example: localAgent

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat

seq integer - This attribute is not used by the File Copy node itself.
Successor nodes (like File Concatenate) use the seq value to
define the order in which the files are being used (i.e.,
concatenated).

File Move
Description
A File Move node is an agent process that moves a predecessor file to a different
location, on the same agent machine. The location of the predecessor file is the file
attribute of a predecessor File node (Watch, Copy, Move, Concatenate, or Essbase).
If multiple File nodes precede this node, only the first is moved; the rest are ignored.

Attributes
agent the alias of the agent that runs this process;

Example: localAgent

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat

seq integer - this attribute is not used by the File Move node itself.
Successor nodes (like File Concatenate) use the seq value to
define the order in which the files are being used (i.e.,
concatenated).

File Concatenate
Description
A File Concatenate node is an agent process that concatenates a set of predecessor
files to a different location, on the same agent machine. The location of the
predecessor files is the file attribute of the predecessor File nodes (Watch, Copy,
Move, Concatenate, or Essbase). If multiple File nodes precede this node, the order
in which they are concatenated is given by the seq attribute of the predecessor
nodes.

metaController User Guide 62

 Attributes
agent the alias of the agent that runs this process;

Example: localAgent

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat

seq integer - this attribute is not used by this File Concatenate node
itself. Successor nodes (like other File Concatenate) use the seq
value to define the order in which the files are being used (i.e.,
concatenated).

File Delete
Description
A File Delete node is an agent process that deletes a set of predecessor files, on the
same agent machine. The predecessor files to be deleted are the predecessor File
nodes (Watch, Copy, Move, Concatenate, or Essbase), provided that they are linked
to the File Delete node via pass_info links. The file attribute of the File
Delete node can be used to specify one additional file to be deleted. It can be left
blank as well.

Attributes
agent the alias of the agent that runs this process;

Example: localAgent

file the full path name of one file to be deleted. Can be left empty.

Example: c:\Program Files\tea\samples\03\emp1.dat

Remote File Watch

Description
A Remote File Watch node is an agent process that completes when a file is detected
on a remote machine with the name and in the directory specified in its attributes.
This node accesses the specified file using the SSH protocol (Secured Shell – see the
Remote File Operations paragraph in the Basic Concepts for more details). The node
could also report an error if the timeout interval has been exhausted and the file has
not appeared.

Attributes
alias an alias for the remote server connection. See the Remote
File Operations paragraph in the Basic Concepts section.

agent the alias of the agent that runs this process

Example: localAgent

metaController User Guide 63

 authentication the authentication method: KEY or PASSWORD. See the
Remote File Operations paragraph in the Basic Concepts
section.

file the full path name of the file that is being watched.

Example 1: c:\Program
Files\tea\samples\03\emp1.dat;

Example 2: /home/user1/watch2.dat

seq integer - this attribute is not used by the File Watch node
itself. Successor nodes (like File Concatenate) use the seq
value to define the order in which the files are being used
(i.e., concatenated).

timeout integer - a value of -1 indicates that metaController waits

indefinitely for the file to appear at the specified file
location on the agent machine. A positive value specifies
that metaController should wait at least that many seconds
before reporting an error.

Remote File Copy

Description
A Remote File Copy node is an agent process that makes a copy of a predecessor file
to a different location anywhere over the network. The location of the predecessor
file is the file attribute of a predecessor File node (Watch, Copy, Move,
Concatenate, or Essbase). The predecessor file can be local or remote over the
network. If multiple File nodes precede this node, only the first is copied; the rest are
ignored.

Attributes
alias an alias for the remote server connection. See the Remote
File Operations paragraph in the Basic Concepts section.

agent the alias of the agent that runs this process

Example: localAgent

authentication the authentication method: KEY or PASSWORD. See the

Remote File Operations paragraph in the Basic Concepts
section.

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat;

/home/user1/watch2.dat

metaController User Guide 64

 seq integer - This attribute is not used by the File Copy node
itself. Successor nodes (like File Concatenate) use the seq
value to define the order in which the files are being used
(i.e., concatenated).

Remote File Move

Description
A Remote File Move node is an agent process that moves a predecessor file to a
different location anywhere over the network. The location of the predecessor file is
the file attribute of a predecessor File node (Watch, Copy, Move, Concatenate, or
Essbase). The predecessor file can be local or remote over the network. If multiple
File nodes precede this node, only the first is moved; the rest are ignored.

Attributes
alias an alias for the remote server connection. See the Remote
File Operations paragraph in the Basic Concepts section.

agent the alias of the agent that runs this process

Example: localAgent

authentication the authentication method: KEY or PASSWORD. See the

Remote File Operations paragraph in the Basic Concepts
section.

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat;

/home/user1/watch2.dat

seq integer - this attribute is not used by the File Move node
itself. Successor nodes (like File Concatenate) use the seq
value to define the order in which the files are being used
(i.e., concatenated).

Remote File Concatenate

Description
A Remote File Concatenate node is an agent process that concatenates a set of
predecessor files to a different location anywhere over the network. The location of
the predecessor files is the file attribute of the predecessor File nodes (Watch,
Copy, Move, Concatenate, or Essbase). The predecessor file can be local or remote
over the network. If multiple File nodes precede this node, the order in which they
are concatenated is given by the seq attribute of the predecessor nodes.

Attributes
alias an alias for the remote server connection. See the Remote
File Operations paragraph in the Basic Concepts section.

metaController User Guide 65

 agent the alias of the agent that runs this process

Example: localAgent

authentication the authentication method: KEY or PASSWORD. See the

Remote File Operations paragraph in the Basic Concepts
section.

file the full path name of the target file.

Example: c:\Program Files\tea\samples\03\emp1.dat;

/home/user1/watch2.dat

seq integer - this attribute is not used by this File Concatenate

node itself. Successor nodes (like other File Concatenate)
use the seq value to define the order in which the files are
being used (i.e., concatenated).

Remote File Delete

Description
A File Delete node is an agent process that deletes a set of predecessor files anywhere
over the network. The predecessor files are the predecessor File nodes (Watch, Copy,
Move, Concatenate, or Essbase), provided that they are linked with the Remote File
Delete node via pass_info links. The predecessor file can be local or remote over
the network. The file attribute of this node can be used to specify one additional
file to be deleted. It can be left blank as well.

Attributes
alias an alias for the remote server connection. See the Remote
File Operations paragraph in the Basic Concepts section.

agent the alias of the agent that runs this process

Example: localAgent

authentication the authentication method: KEY or PASSWORD. See the

Remote File Operations paragraph in the Basic Concepts
section.

file the full path name of a file to be deleted. It can be left

blank.

Example: c:\Program Files\tea\samples\03\emp1.dat;

/home/user1/watch2.dat

metaController User Guide 66

Database Processes
Oracle Load
Description
An Oracle Load process is an agent process that performs a SQL Load operation
from one predecessor file to an Oracle table. The location of the predecessor file is
the file attribute of the predecessor File node (Watch, Copy, Move, Concatenate,
or Essbase). If multiple File nodes precede this node, only the first is loaded; the rest
are ignored.

Attributes
agent the alias of the agent that runs this process;

Example: localAgent

bad the name of the SQL Load bad file. Optional.

control the name of the SQL Load control file. Mandatory.

direct the direct keyword value on the SQL Load command line.
Optional.

discard the name of the SQL Load discard file. Optional.

log the name of the SQL Load log file. Mandatory.

parfile the name of the SQL Load parameter file. Optional.

uidtns uid@tns, where uid and tns are the user id and tns respectively
used for the load operation. The password required to access the
database is stored in the metaController repository using the
Admin utility. If a password is not defined for the combination
uid @ tns, the node reports a Database Configuration Error.

Example: [email protected]

Stored Procedure
Description
A Stored Procedure node is a server process that executes a SQL stored procedure,
optionally returning one numerical result. The result – if applicable - is saved as a
metaController parameter named $value$ and is available to subsequent nodes in
the flow. The $value$ parameter is implicitly used by conditional links (see the
paragraph on Conditional Links in the Advanced Topics section).

Attributes
datasource the name of the datasource for this stored procedure. See the
Data Sources paragraph in the Basic Concepts section for more
details.

metaController User Guide 67

 Example 1:TEAMC

Example 2: myDB2DataSource

procedure the name of the procedure to be executed; the parameters must

be hard coded in the procedure name (but you can use
metaController parameters to specify a variable part).

Example 1: tlm_sam_wait_5secs(<%=number_of_seconds%>)

Example 2: tlm_sam_rand_num(?) – the stored procedure

returns an integer parameter.

OLAP Processes
Essbase File
Description
An Essbase File node is an agent process that waits for an Essbase rules file (similar
to a File Watch process). It contains additional attributes that are not used by the
node itself, but by successor Dim Build nodes.

Attributes
agent the alias of the agent that runs this process

datafile not used by the Essbase File node itself. A successor Essbase
Dim Build node uses the datafile value to build a
dimension. See Essbase Dim Build process below.

Example: d:\hyperion\essbase\app\APITest\DimData\view

errorfile not used by the Essbase File node itself. A successor Essbase
Dim Build node uses the errorfile value while building a
dimension. See Essbase Dim Build process below.

Example:
d:\hyperion\essbase\app\APITest\DimData\accounts.err

essFile the full path name of the rule file that is being watched

Example:
d:\hyperion\essbase\app\APITest\APITest\acctsql.rul

seq integer - this attribute is not used by the Essbase File node itself.
Successor nodes (like Essbase Dim Build) use the seq value to
define the order in which the files are being used. See Essbase
Dim Build process below.

timeout -1 - a value of -1 indicates that metaController waits indefinitely

for the file to appear at the specified ruleFullPathName location

metaController User Guide 68

 on the agent machine. A positive value specifies that
metaController should wait at least that many seconds before
reporting an error.

uidtns uid@tns - this attribute is not used by the Essbase File node
itself. A successor Essbase Dim Build node uses the uidtns
value to build a dimension. See Essbase Dim Build process
below.

The password required to access the database is stored in

metaController using the Admin utility. If a password is not
defined for the uid and tns, the node reports a Database
Configuration Error.

Example: tea_lm05@trvsora:1521:maf21

Essbase Dim Build

Description
An Essbase Dim Build node is an agent process that builds a set of dimensions in
Essbase.

The set of dimensions is derived from the set of predecessor Essbase File nodes. The
dimensions are built in the order established by the seq attributes of all predecessor
nodes. In a predecessor Essbase File node, either a datafile or a uidtns
attribute must be present.

The credentials used to access the Essbase server are input into metaController via
the Admin utility, and associate the agent alias with the server IP address, user id, and
password. If such an association is not present, an Essbase Configuration Error is
reported.

Attributes
agent the alias of the agent that runs this process.

cleardb Y/N - specifies whether the database is cleared before building

the dimensions.

essApplication the name of the Application in which the dimensions are built.

essDatabase the name of the Database in which the dimensions are built.

Essbase Import
Description
An Essbase Import node is an agent process that imports a set of files into Essbase.
The files are extracted from predecessor nodes (File Watch or Essbase File).

Attributes
agent the alias of the agent that runs this process.

metaController User Guide 69

 cleardb Y/N - specifies whether the database is cleared before importing
the files.

essApplication the name of the Application in which the data is imported.

essDatabase the name of the Database in which the data is imported.

Essbase Calc
Description
An Essbase Calc node is an agent process that executes an Essbase calc script.

Attributes
agent the alias of the agent that runs this process.

calcDefault Y/N - specifies whether or not the default script should be used
(CALC ALL;).

calcFile @todo – what is it used for?.

calcScript if the calcDefault attribute is N, specifies the text of the script to

be executed.

essApplication the name of the Application in which the script is executed.

essDatabase the name of the Database in which the script is executed.

Essbase Commands
Description
An Essbase Commands node is an agent process that executes an Essbase command.

Attributes
agent the alias of the agent that runs this process.

essApplication the name of the Application in which the command is executed.

essCommand the Essbase command to be executed; the available commands

are: clearDatabase, loadApplication,
setActive, unloadAppliation.

essDatabase the name of the Database in which the command is executed.

HyperRoll Attach
Description
A HyperRoll Attach node is an agent process that executes the HyperRoll Attach
command.

Attributes
agent the alias of the agent that runs this process.

metaController User Guide 70

 aggregation @todo - description.

application @todo - description.

cubeName @todo - description.

database @todo - description.

measure @todo - description.

option @todo - description.

outline @todo - description.

password @todo – description – move it out of here into Admin utility.

user @todo - description.

HyperRoll Command
Description
A HyperRoll Command node is an agent process that executes a HyperRoll
command.

Attributes
agent the alias of the agent that runs this process.

command @todo - description.

cubeName @todo - description.

eOptions @todo - description.

hdfFile @todo - description.

iOptions @todo - description.

Set HyperRoll
Description
A Set HyperRoll node is an agent process that executes a Set Hyper command.

Attributes
agent the alias of the agent that runs this process.

application @todo - description.

database @todo - description.

filesPath @todo - description.

metaController User Guide 71

 option @todo - description.

outline @todo - description.

password @todo – description – move it out of here into Admin utility.

user @todo - description.

Miscellaneous Processes
Time
Description
A Time node is a server process that waits for a specified time to become
COMPLETED. The attributes are similar to the Unix command cron parameters. If
all attributes are * the next scheduled event occurs at the beginning of the next
minute. All time related attributes (dayOfMonth, dayOfWeek, hour, minute, month,
year) accept lists of *’s or numbers separated by commas. The earliest time satisfying
the criteria is the scheduled time.

Attributes
allow_past Y/N - a value of N specifies that if the next scheduled date is in
the past then the result of the execution of this node is an
ERROR. Otherwise, the node status is immediately changed to
COMPLETED.

dayOfMonth * or 1-31 - a value of * does not restrict the day of month portion
of the scheduled time. An integer value of 1 specifies that the
next scheduled event should occur on the 1st of the month,
whichever that month is.

dayOfWeek * or 0-6 - a value of * does not restrict the day of week portion of
the scheduled time. An integer value of 1 specifies that the next
scheduled event should occur on Sunday, whichever day of the
month that is.

hour * or 1-24 - a value of * does not restrict the day of month portion
of the scheduled time. An integer value of 1 specifies that the
next scheduled event should occur on the 1st of the month,
whichever that month is.

minute * or 0-59 - a value of * does not restrict the minute portion of the
scheduled time. An integer value of 30 specifies that the next
scheduled event should occur on the next half hour mark.

month * or 1-12 – a value of * does not restrict the day of month

portion of the scheduled time. An integer value of 7 specifies that
the next scheduled event should occur during the respective
month (1 for January and so on).

metaController User Guide 72

 year * or a number - a value of * does not restrict the year portion of
the scheduled time. An integer value specifies that the next
scheduled event should occur during the specified year.

Example: To schedule a task on the quarter hour, one needs to set the
minute value to the list 0,15,30,45.

OS Command
Description
An OS Command node is an agent process that executes an OS command (such as a
.bat file, or an executable program).

Attributes
agent the alias of the agent that runs this process.

command the OS command to be executed, including parameters

Example: cmd /C pkzip -u C:\teamc\samples\ex14\archive\emp.zip

C:\teamc\samples\ex14\archive\emp1.dat

Parameters
Description
A Parameters node is a server process that generates parameter (name, value) pairs
and makes them available to successor nodes. See the basic concepts section for a
discussion of how parameters are used. In addition to the name and sql attributes,
hard coded values for parameters can be created using the Add Property button in
the TEA Object Inspector. The name of the attribute is the parameter name and the
attribute value is the parameter value.

Attributes
datasource the name of the datasource used to execute the sql statement
below. See the Basic Concepts section for more details.

sql_type name_value or column_based - specifies how the sql

statement results will be interpreted. See below.

sql a sql statement that returns (1) a result set with 2 columns and as
many rows as necessary if the value of sql_type attribute is
name_value; and (2) a result set with as many columns as
necessary but one single row if the value of sql_type attribute
is column_based. In the first case the first column value is the
name of the parameter and the second column is the parameter
value. In the second case the column name is the parameter
name and the column value is the parameter value.
Example 1: SELECT par_name, par_value FROM TLM_SAM_PARAMS
WHERE test_id=14
will generate the following parameters: (agent, localAgent),
(demoroot, D:\Program Files\tea\mc\samples\14), (schema,

metaController User Guide 73

 tea_mc1). The following variable constructs could then be used
in the attributes of successor nodes: <%=agent%>,
<%=demoroot%>, <%=schema%>.
Example 2: SELECT par_value AS agent FROM TLM_SAM_PARAMS
WHERE test_id=14 AND par_name = 'agent'
will generate the following parameter: (agent, localAgent).

E-Mail
Description
An E-Mail node is a server process that sends mail to one or more recipients. All attributes can contain parameters, which
will be expanded before the mail message is sent out.
Attributes
attachments A list of files to be attached to the mail message. The files must be separated by commas
(“,”). Can be left empty.

body The body of the message to be sent to the recipients.

cc The list of Cc recipients that will receive the message. Must be

email addresses separated by spaces.

from The e-mail address of the person on whose behalf the message will be sent.

subject The subject line of the mail message.

to The list of To recipients that will receive the message. Must be

email addresses separated by spaces.

JMS Watch
Description
A JMS Watch node is an agent process that consumes one message from a JMS
queue / topic. The JMS timestamp header value is made available to successor nodes
as the $jmsTimestamp$ parameter.

Attributes
agent The alias of the agent that runs the JMS Watch process.

jmsPool The name of the jms connection pool used to access the queue /
topic (defined via the Admin utility).

parser com.traversesys.tea.agent.TEAMapMessageParser - the name of

a class implementing interface
com.traversesys.tea.agent.TEAJMSMessageParser. Its
parseMessage method takes a Message as a parameter and
returns a Hashtable ((name, value) pairs). These parameters are
made available to subsequent nodes in the workflow graph. The
default value handles MapMessages, but classes to handle
different types of messages can be written (e.g., XML, object,
etc.).

metaController User Guide 74

 queue the queue / topic id that the service is monitoring

selector a JMS selector expression that allows filtering of messages to be

consumed by the JMS Consumer service. If null, the first
message in the queue/topic will be processed; however, if there
are multiple nodes connected to the same queue with no selector
expression, the way the messages are assigned for processing to
the available nodes is undefined.

Example: mod2='1'

timeout -1 - the timeout interval (in seconds) before an absence of a

message in the queue/topic is flagged as an error. A value of -1
signifies no limit; metaController waits forever.

DataStage Run Job

Description
A DataStage Run Job node is an agent process that executes a DataStage job. The
result of the execution – an integer value – is saved as a metaController parameter
named $value$ and is available to successor nodes in the flow. The $value$
parameter is implicitly used by conditional links (see the Basic Concepts section for a
discussion of conditional links).

The possible values returned by the DataStage Run Job node are: 1 - the job
completed normally; 2 - the job completed with warnings; 3 – the run failed; 4 – the
run was stopped; 5 – the job is not runnable (not compiled); 6 – the job is not
running; and 7 – unknown return code.

Attributes
agent The alias of the agent that runs the DataStage Run Job process.

alias The connection alias which associates the DataStage server/user

with the password used to execute the DataStage job. See the
DataStage paragraph in the Administration section for
information on how to define DataStage aliases.

job the name of the DataStage job to be executed

params the DataStage job parameters in the format

param1=value1|param2=value2|param3=value3 … The
parameters are separated by metaController and passed to
DataStage when executing the job.

project the DataStage project containing the job to execute.

metaController User Guide 75

SubFlow
Description
A SubFlow node groups other regular nodes or SubFlows. A SubFlow node is
created when you group a set of nodes. See the Grouping paragraph in the Advanced
Topics section.

Attributes
datasource The name of the datasource used to execute the sql
statement below. See the Basic Concepts section for more
details about named resources.

return Used only for ERR_HANDLER flows; the value returned by

the handler flow; see the Error Handling paragraph in the
Advanced Topics section.

sql Used only for SUB_ROUTINE flows; a SQL statement; see

the Subroutine Execution paragraph in the Advanced Topics
section.

subflow_type REGULAR, SUB_ROUTINE, ERR_HANDLER.

Sub Call
Description
A Sub Call node initiates for execution one or more instances of one or more
SubFlow’s. See the Subroutine Execution paragraph in the Advanced Topics section.

Attributes
datasource The name of the datasource used to execute the sql statement
below. See the Basic Concepts section for more details.

failOnNone Y/N – specifies whether an empty routine set returned by the

sql/sub attributes below results in an error. Default value is Y.

sql A SQL statement that must return a result set containing a

column named ‘sub’ (optional).

sub The name of one sub routine flow to be called (optional).

ILOG JRule
Description
A JRule node is an agent process that invokes an instance of an ILOG JRules engine
and generates metaController events, which in turn are detected using Event Watch
nodes. The rule stored in the rule file returns a set of strings which will match the
node_id attributes of Event Watch nodes.

Attributes
agent The alias of the agent that runs this process.

metaController User Guide 76

 datasource The name of the datasource used to access the rule repository if
ruletype is Repository.

packageName The name of the package where the rule is stored if ruletype
is Repository.

projectName The name of the rule (project) if ruletype is

Repository.

rulefile Full path name location of the ILOG rule file if ruletype is
RuleFile.

Example: c:\Program Files\tea\samples\TestRuleFile.ilr

ruletype Repository/RuleFile – specifies where the rule can be

found.

Event Watch
Description
An EventWatch process is an agent process that completes when an event for
node_id is detected on the agent. The node could also report an error condition if the
timeout interval has been exhausted and the event for node_id has not occured.

Attributes
agent The alias of the agent that runs this process.

node_id Node identifier; the process completes when a JRule node

produces a value matching this node id.

timeout Integer - a value of -1 indicates that metaController waits

indefinitely for the event to appear on the agent machine. A
positive value specifies that metaController should wait at least
that many seconds before reporting an error.

StageDirector
Description
A StageDirector node is a server process that sends a SOAP message to a
StageDirector application, and waits until the StageDirector application completes,
when it reports completion itself.

Attributes
application The StageDirector application to be invoked.

form The StageDirector form to be used to initiate a workflow

process.

link Application data passed as is to the StageDirector application.

metaController User Guide 77

sd_url The url where the StageDirector (WSDL) web service is located.

Example:
https://localhost:9001/cr/review.wsdl

uid The user id to access the StageDirector application. The

password corresponding to this user id is stored in the
metaController repository using the Admin utility. Note that
these are the credentials on the remote system.

version The version of the StageDirector form used to initiate the

workflow process.

metaController User Guide 78

 As soon as you save the flow to the repository, the metaController engine starts
processing. Click the ‘Monitor the Process Schema’ button in the metaController
toolbar to enable Monitor mode. From now until you click the ‘Monitor the Process
Schema’ button again, the metaController client will receive all status modification
messages from the server and will display this information as changing colors on the
flow diagram, and in the execution log window.

Example 01 – Independent Flows

Example 01 consists of two independent flows, each of them consisting in turn of a
Params node and several Stored Procedure nodes. The Params nodes retrieve the
parameter information from the TEAMC datasource which corresponds to the
repository (table TMC_SAM_PARAMS). The ‘datasource’ attribute of the Stored
Procedure nodes is the <%=ds%> parameter, which by default has value TEAMC.
Using the Admin utility you can define other datasources and modify the respective
entries in the repository TMC_SAM_PARAMS table.

The database identified by the datasource attribute must have a procedure named
tlm_sam_wait_5secs with one numeric input as argument.

Example 02 – Boundary Nodes

Example 02 tests boundary nodes (see the paragraph on Boundary Nodes in the
Advanced Topics section).

Example 03 – File Operations

Example 03 tests File operation nodes. As soon as files watch1 and watch3 arrive on
the localAgent machine they are concatenated into file watch, which is then copied
to sub directory cpy; as soon as the copy completes, the source watch is moved to
the mov sub directory.

Example 04 – Regular Sub Flows

Example 04 test regular SubFlows, more specifically links to/from SubFlows.
metaController allows links from a node to another node inside a regular SubFlow or
from a node inside a regular SubFlow to a node (e.g., from node [1] to node [2]; from
node [2] to node [3]; and from node [6] to node [3]); or from a node to a SubFlow
(e.g., from node [2] to SubFlow [10] – the group that contains node [4]); or from a
SubFlow to a node (from SubFlow [10] to node [13]).

metaController User Guide 112

Example 05 – Oracle Load
Example 05 expands on example 04, adding Oracle Load.

Example 06 - JMS
Example 06 tests the JMSWATCH node.

You need to have WebLogic 6.1 installed and configured as a JMS provider in order
to run this example. Create a new Connection Factory called teamcQueue with JNDI
name com.traversesystems.teaQueueConnectionFactory. Create a new File Store
called teaJMSFileStore in directory MC_HOME. Create a new JMS server called
teaJMSServer using the teaJMSFileStore. In this server, create a new JMS Queue
(Destination) called teamcQueue with JNDI name com.traversesystems.teaQueue.
Make sure to deploy the Connection Factory and the JMS Server in the proper
WebLogic domain.

Using the metaController Admin utility set up a new Messaging Pool named
TEAMC. Set the values of the following properties as indicated.

User Id system

Password your_password_here

Context Factory weblogic.jndi.WLInitialContextFactory

JMS Factory com.traversesystems.teaQueueConnectionFactory

JMS Queue Name teamcQueue

Pool Type Pooled

Pool Size 10

JMS URL t3://localhost:7001

Save the flow to the repository. Both WLS teaQueue nodes will start execution ([100]
and [200]), waiting for a message from WebLogic on queue teamcQueue, and its
color will be yellow. Run the jmsTest utility in your metaController installation to
deposit one message in the teamcQueue. You will notice that one of the
JMSWATCH nodes turns green and the execution of that flow continues. Examine
the execution log window to see the parameters created by the JMSWATCH node.
Examine table TLM_SAM_PARAMS for the records with test_id=15 to see the
exact values that the jmsTest utility put on the queue. Notice that the selector
attribute is randomly generated in the jmsTest program, resulting in only one flow
being executed at one time.

metaController User Guide 113

Example 06-1 – MQ Series
Example 06-1 tests the JMSWATCH node. You need to have IBM MQ Series
installed and configured in order to run this example. See the paragraph on
Configuring IBM MQ Series in the Installation section.

Save the flow to the repository. The MQ teamcQueue node will start execution,
waiting for a message from MQ on queue teamcQueue, and its color will be yellow.
Run the jmsTest utility in your metaController installation to deposit one message in
the teamcQueue. You will notice that the JMSWATCH node turns green and the
execution of the flow continues. Examine the execution log window to see the
parameters created by the JMSWATCH node. Examine the MQMessage.xml file in
your metaController bin directory to see the exact message that the jmsTest utility put
on the queue. Notice that the selector attribute is hard coded in the jmsTest program.

Example 07 – Parallel Execution

Example 07 is designed to test parallel execution of similar nodes. It also tests the
Time node. Out of the box files watch5, watch6, and watch7 are not in the
samples/07/data sub directory of the metaController installation. Copy these files
from the samples/07/data/src sub directory. Once a cycle is complete, files
watch5, watch6, and watch7 are moved to the moved sub directory. To execute a
new cycle, copy these files again.

Example 08 – Remote File Operations

Example 08 tests regular and remote file operations. Out of the box it uses both
password and key based authentication, with an alias named ‘orcl.’ In order to execute
this sample you need to set up an OS User with alias ‘orcl’ (see the Admin utility
documentation), store an SSH private key file on the mcAgent machine (see the
paragraph on Configuring SSH in the Installation section), and specify its location in
the configuration file teamc.xml. You also need to copy a file named watch.dat in
the home directory of the respective user. The example will copy that file first to the
cpy sub directory, then move the copy to the mov directory, and finally concatenate
this latter file with a local copy and store the result in file watchCat.dat in the home
directory of the user on the remote machine.

Example 15 – Manual Recover Actions

Example 15 is designed to test manual restart actions. Out of the box, file
watch22.dat (node [190]) does not exist in the samples data directory. Therefore,
node [190] will remain in INPROCESS status (yellow color) for ever. Use the
Recover ERROR action to cancel the File watch process and then use the Recover
READY2GO action to restart the process from any prior node (see Correcting
Execution Problems in the Advanced Topics section). Requires a localAgent to run.

metaController User Guide 114

Example 18 - DataStage
Example 18 tests the DataStage node. You need to have a DataStage installation
available and a DataStage alias (named dsServer) defined via the metaController
Admin utility.

Job TestJob is executed in project meta-proj on the DataStage server using credentials
defined in the dsServer DataStage alias. The parameters passed to the job are hard
coded in the params attribute of the node. If the return code of the DataStage node is
1 or 2 (job completed with or without warnings) then node [3] is executed, otherwise
node [4] is executed (job encountered an error; see the execution log for more
details).

Example 19 – File Delete

Example 19 tests the regular File Delete node. The files to be deleted include the
optional file specified in the node plus all predecessor files, provided they are linked
with the delete node via pass_info links (node [22]). See the Link Attributes
paragraph in the Basic Concepts section. Requires a localAgent to run.

Example 20 – Simplest Overlapped Flow

Example 20 tests boundary nodes – it is the simplest overlapped flow with three
sections each consisting only of the boundary node.

Example 21 – Overlapped Flow

Example 21 is a more elaborate version of example 20, with additional nodes in each
section.

Examples 22 and 23 – Flow with two Periodicities

These examples illustrate running two parallel flows with different periodicities, but
with one connect point. It simulates a monthly flow (nodes [94], [92], [95]) that
computes and makes available the monthly data to the daily flow (nodes [9], [93],
[91]). The node that caches the data is node [93]. See the paragraph on Executing
Processes with Different Periodicities in the Advanced Concepts section.

metaController User Guide 115

Example 25 – Conditional Links and Periodicities
Example 25 combines a two periodicities flow with conditional links. See the
Executing Processes with Different Periodicities and Conditional Execution
paragraphs in the Advanced Concepts section.

Based on the returned random number, one of nodes [72] and [74] is executed. When
the selected one completes, node [82] can be evaluated.

Example 30-recover – Error Handling via Recovery Actions

See the Error Handling via Recovery Actions paragraph in the Advanced Concepts
section.

Example 30-return – Error Handling via Return Codes

See the paragraph on Error Handling via Return Codes in the Advanced Concepts
section.

Example 31 - JRules
Example 31 exemplifies the operation of the JRule and Event Watch nodes. The
JRule node [11] exaluates the rule stored in the JRule file RuleFile.ilr and creates
events for each
result.addFileGroup(FlowName);

statement executed. In this particular case, an event is generated for each of the three
flows, FlowOne, FlowTwo, and FlowThree.

Example 32 – Sub Routine execution

Sample 32 exemplifies sub routine execution. When node [3] evaluates its SQL
statement, 5 records are returned: (sub1, 51), (sub1, 52), (sub2, 53), (sub2, 54), and
(sub2, 55). Therefore 2 instances of sub1 and 3 instances of sub2 will be started,
passing the second column of the result as parameter named pid.

Based on the passed pid parameter, each sub routine computes additional parameters:
sub1 extracts values for parameters p11 and p12; and sub2 extracts values for
parameter p21. In turn, these parameters are passed to nodes [13] and [23]
respectively which use test procedure tlm_sam_log to log the values into a sample
repository table. You can examine table TLM_SAM_LOG for these entries.

Use the Execution Tree to visualize the called sub routine flows.

metaController User Guide 116

Example 33 – More complex Sub Routine execution
Sample 33 presents a flow that calls a sub routine flow which in turn calls another sub
routine flow. Use the flow file specific for your repository database.

When executed, the JRule node produces two events: one for the Product
Information flow (node [11]) and one for the Customer Information flow (node
[12]). Each such Event Watch node is followed by a SubCall node which invokes two
instances of the FILECOLLECTION sub routine flows. Node [102] in the
FILECOLECTION routine is itself a SubCall node, which will call only one instance of
the FILEMOVE sub routine flow.

In order to be able to run the flow repeatedly, routine FILEMOVE actually makes a
copy of its input parameter file from the designated directory to the history directory
(instead of moving it).

Node [105] executes a stored procedure that specifies whether the file is in the
standard directory or in the alternate directory, based on the file name. If the stored
procedure returns 2 then node [106] is executed. This will overwrite the existing
SOURCE_DIR parameter with a new value. Otherwise node [106] is not executed and
node [107] will look for its file in the default directory.

Example 34 – Error Handling

Example 34 is similar with example 33, except that it has an error handling
mechanism on node [107]. If the sought file is not in the specified location within a
specified timeout period, then myErrorHandler is executed which logs the error
message to a sample repository table and returns 3 to its caller (node [107]). Node
[107] is linked to its successors (nodes [108] and [109]) via conditional links. If the
error handler has been executed (the value of the $value$ parameter is 3) then node
[108] is not executed – the copy operation is skipped since it will fail. In either case,
node [109] is executed.

Example 35 – StageDirector External Flow

Sample 35 exemplifies connecting a metaController flow with an external workflow
system. It requires an installation of StageDirector workflow engine and the Cube
Review demo application.

When the StageDirector node is executed, it starts a new workflow instance for
StageDirector application Cube Review (cr), form main, version 1, in the
StageDirector installation. The external Cube Review application sends an e-mail
notification to a human reviewer who follows the link provided in the link attribute
to examine a particular document. The reviewer approves or rejects the document

metaController User Guide 117

 thus completing the external flow. The decision of the human reviewer is passed back
to the metaController flow and used to execute either node [13] or [15].

Example 36 – Complex Flow (Essbase, HyperRoll, StageDirector)

Example 36 is a complex flow, involving OLAP nodes and external flows. You need
to have Essbase, HyperRoll, and StageDirector in order to run this example.

The fact data file arrives at a pre-determined location (node [12]), gets moved to a
staging area (node [13]), gets loaded into an Oracle table (node [14]), and an ETL
stored procedure is executed on it. In parallel, an Essbase OTL template is copied
from its source location to the work directory, and an Essbase rule file is watched.
When all the three above flows complete, a dimension gets built in Essbase (node
[19]), then a HyperRoll Set node and a HyperRoll Calc node are executed in
sequence. At this step the cube is ready for a human review. A StageDirector flow is
invoked (node [22]) after which a HyperRoll Attach node is executed, which will
publish the cube.

Example 37 – Email node

Example 37 tests the capabilities of the Email node, including computing the mail
fields from parameters at run time, and attaching files to the email message. You need
to specify the email server details using the metaController Admin utility. See the
paragraph on Email Dispatcher in the Administration section.

metaController User Guide 118