Sun Microsystems 3.0 iPlanet Integration Server User Guide
Below you will find brief information for Integration Server. This guide details the configuration, management, and troubleshooting of the iPlanet Integration Server, which facilitates the integration of various applications and systems by providing an environment for process management and execution.
advertisement
Process System Guide
iPlanet™ Integration Server
Version 3.0
August 2001
Copyright (c) 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, U.S.A. All rights reserved.
Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries.
This document and the product to which it pertains are distributed under licenses restricting their use, copying, distribution, and decompilation. No part of the product or of this document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.
Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.
Sun, Sun Microsystems, the Sun logo, Java, iPlanet and the iPlanet logo are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries.
All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc.
UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.
This product includes software developed by Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999 The
Apache Software Foundation. All rights reserved.
Federal Acquisitions: Commercial Software – Government Users Subject to Standard License Terms and Conditions.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE
LEGALLY INVALID.
Copyright (c) 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, Etats-Unis. Tous droits réservés.
Sun Microsystems, Inc. a les droits de propriété intellectuels relatants à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et sans la limitation, ces droits de propriété intellectuels peuvent inclure un ou plus des brevets américains énumérés à http://www.sun.com/patents et un ou les brevets plus supplémentaires ou les applications de brevet en attente dans les Etats - Unis et dans les autres pays.
Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l'utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, parquelque moyen que ce soit, sans l'autorisation préalable et écrite de Sun et de ses bailleurs de licence, s'il y ena.
Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun.
Sun, Sun Microsystems, le logo Sun, Java, iPlanet et le logo iPlanet sont des marques de fabrique ou des marques déposées de Sun
Microsystems, Inc. aux Etats-Unis et dans d'autres pays.
Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC
International, Inc. aux Etats-Unis et dans d'autres pays. Les produits protant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.
UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et licenciée exlusivement par X/Open Company, Ltd.
Ce produit inclut des logiciels développés par Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999 The
Apache Software Foundation. Tous droits réservés.
Acquisitions Fédérales: progiciel – Les organisations gouvernementales sont sujettes aux conditions et termes standards d'utilisation.
LA DOCUMENTATION EST FOURNIE “EN L'ÉTAT” ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES
EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y
COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE
UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFAÇON.
Contents
3
iIS Process Management Tasks (continued)
4 iPlanet Integration Server • Process System Guide • August 2001
5
6 iPlanet Integration Server • Process System Guide • August 2001
7
8 iPlanet Integration Server • Process System Guide • August 2001
Managing iIS Process Engines with Conductor Script
(continued)
9
Conductor Script Commands (continued)
10 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands (continued)
11
12 iPlanet Integration Server • Process System Guide • August 2001
List of Figures
13
14 iPlanet Integration Server • Process System Guide • August 2001
List of Procedures
15
16 iPlanet Integration Server • Process System Guide • August 2001
List of Procedures 17
18 iPlanet Integration Server • Process System Guide • August 2001
Preface
The iIS Process System Guide describes how to manage a process system, one of the two subsystems that comprise iIS. The guide provides the system management principles and concepts upon which a process system is based, and describes how to perform process system management tasks.
This preface contains the following sections:
•
“Product Name Change” on page 19
•
“Audience for This Guide” on page 20
•
“Organization of This Guide” on page 20
•
•
“Other Documentation Resources” on page 22
•
“iIS Example Programs” on page 24
•
“Viewing and Searching PDF Files” on page 24
Product Name Change
Forte Fusion has been renamed the iPlanet Integration Server. You will see full references to the new name, as well as the abbreviation iIS.
19
Audience for This Guide
Audience for This Guide
This book assumes familiarity with the basic concepts underlying an iIS process system. A discussion of these concepts and a description of iIS process system components, the functions they perform, and how they interact with an iIS
Backbone can be found in the iIS Conceptual Overview. Additionally, information about creating and defining business process for use within an iIS process system can be found in the first two chapters of the iIS Process Development Guide.
Because an iIS system is built and distributed in an iPlanet UDS environment, it is helpful to understand iPlanet UDS system management concepts. For details, see the iPlanet UDS System Management Guide.
Organization of This Guide
The following table briefly describes the contents of each chapter:
Chapter
Description
Provides a brief introduction to the iIS process engine and process system management.
Describes the components of an iIS process system and how to distribute them among the different nodes in your environment.
Introduces the iIS Console, an interactive system management tool.
Explains how to configure, start up, and manage an iIS process engine and its components.
Describes the registration process by which process definitions and other development components are made available for execution by a running engine.
Explains how an engine executes process definitions and how to monitor and make adjustments to process execution.
Explains tools and techniques used for diagnosing problems in process execution.
20 iPlanet Integration Server • Process System Guide • August 2001
Text Conventions
Chapter
Chapter 8, “Using the Conductor
Description
Explains how to perform iIS system management tasks using Conductor Script commands.
Provides a command reference for Conductor Script, a command line tool for process system management.
Provides a reference for the iIS process engine database schema.
Text Conventions
This section provides information about the conventions used in this document.
Format italics monospace
ALL CAPS
Key+Key
Key-Key
Description
Italicized text is used to designate a document title, for emphasis, or for a word or phrase being introduced.
Monospace text represents example code, commands that you enter on the command line, directory, file, or path names, error message text, class names, method names (including all elements in the signature), package names, reserved words, and URLs.
Text in all capitals represents environment variables
(FORTE_ROOT) or acronyms (iIS, JSP, iMQ).
Uppercase text can also represent a constant. Type uppercase text exactly as shown.
Simultaneous keystrokes are joined with a plus sign: Ctrl+A means press both keys simultaneously.
Consecutive keystrokes are joined with a hyphen: Esc-S means press the Esc key, release it, then press the S key.
Preface 21
Other Documentation Resources
Syntax Statements
Syntax statements that describe usage of TOOL methods and script commands use the following conventions:
Format Description parentheses ( ) Parentheses enclose a parameter list.
comma , Commas separate items in a parameter list. vertical bars | Vertical bars indicate a mutually exclusive choice between items. See braces and brackets, below.
brackets[] Square brackets to indicate optional values in a syntax statement.
braces { } ellipsis …
Braces indicate a required clause. When a list of items separated by vertical bars is enclosed in braces, you must enter one of the items from the list. Do not enter the braces or vertical bars.
The item preceding an ellipsis may be repeated one or more times.
When a clause in braces is followed by an ellipsis, you can use the clause one or more times. When a clause in brackets is followed by an ellipsis, you can use the clause zero or more times.
Other Documentation Resources
In addition to this guide, there are additional documentation resources, which are listed in the following sections. The documentation for all iIS products can be
found on the iIS CD. Be sure to read “Viewing and Searching PDF Files” on page 24
to learn how to view and search the documentation on the iIS CD.
iIS documentation can also be found online at http://docs.iplanet.com/docs/manuals/iis.html
.
The titles of the iIS documentation are listed in the following section.
22 iPlanet Integration Server • Process System Guide • August 2001
Other Documentation Resources
iPlanet Integration Server Documentation
iIS Adapter Development Guide iIS Backbone Integration Guide iIS Backbone System Guide iIS Conceptual Overview iIS Installation Guide iIS Process Client Programming Guide iIS Process Development Guide iIS Process System Guide
Online Help
When you are using an iIS development application, press the F1 key or use the
Help menu to display online help. The help files are also available at the following location in your iIS distribution: FORTE_ROOT/userapp/forte/cln/*.hlp
.
When you are using a script utility, such as FNscript or Cscript, type help from the script shell for a description of all commands, or help
<command>
for help on a specific command.
Documentation Roadmap
A roadmap to the iIS documentation can be found in the iIS Conceptual Overview manual.
Preface 23
iIS Example Programs
iIS Example Programs
iIS example programs are shipped with the iIS product and installed in two locations, one for process development (using the process engine) and one for application integration (using the iIS backbone).
Process Development Examples Process development examples are installed at the following location:
FORTE_ROOT/install/examples/conductr
The PDF file, c_examp.pdf
, describes how to install and run the examples in this directory. The Appendix to the iIS Process Development Guide also describes how to install and run the examples.
Application Integration Examples Process integration examples are installed at the following location:
FORTE_ROOT/install/examples/fusion
Each example has its own sub-directory, which contains a README file that explains how to install and run the example.
Viewing and Searching PDF Files
You can view and search iIS documentation PDF files directly from the documentation CD-ROM, store them locally on your computer, or store them on a server for multiuser network access.
NOTE You need Acrobat Reader 4.0+ to view and print the files. Acrobat
Reader with Search is recommended and is available as a free download from http://www.adobe.com
. If you do not use Acrobat
Reader with Search, you can only view and print files; you cannot search across the collection of files.
➤ To copy the documentation to a client or server
1.
Copy the doc directory and its contents from the CD-ROM to the client or server hard disk.
You can specify any convenient location for the doc
directory; the location is not dependent on the iIS distribution. You may want to consolidate your iIS documentation with the documentation for your iPlanet UDS distribution.
24 iPlanet Integration Server • Process System Guide • August 2001
Viewing and Searching PDF Files
2.
Set up a directory structure that keeps the iisdoc.pdf
and the iis
directory in the same relative location.
The directory structure must be preserved to use the Acrobat search feature.
NOTE To uninstall the documentation, delete the doc
directory.
➤
To view and search the documentation
1.
Open the file iisdoc.pdf
, located in the doc directory.
2.
Click the Search button at the bottom of the page or select Edit > Search >
Query.
3.
Enter the word or text string you are looking for in the Find Results Containing
Text field of the Adobe Acrobat Search dialog box, and click Search.
A Search Results window displays the documents that contain the desired text.
If more than one document from the collection contains the desired text, they are ranked for relevancy.
NOTE For details on how to expand or limit a search query using wild-card characters and operators, see the Adobe Acrobat
Help.
4.
Click the document title with the highest relevance (usually the first one in the list or with a solid-filled icon) to display the document.
All occurrences of the word or phrase on a page are highlighted.
Preface 25
Viewing and Searching PDF Files
5.
Click the buttons on the Acrobat Reader toolbar or use shortcut keys to navigate through the search results, as shown in the following table:
Toolbar Button Keyboard Command
Next Highlight Ctrl+]
Previous Highlight Ctrl+[
Next Document Ctrl+Shift+]
6.
To return to the iisdoc.pdf
file, click the Homepage bookmark at the top of the bookmarks list.
To revisit the query results, click the Results button at the bottom of the iisdoc.pdf
home page or select Edit > Search > Results.
26 iPlanet Integration Server • Process System Guide • August 2001
Chapter 1
Introduction: iIS Process
Management
iIS process system management is largely devoted to managing iIS process engines and the functions they perform.
This chapter provides a high level description of what an iIS process engine is and what it does. It describes the relationship of the engine to other parts of the iIS system and describes its component parts.
This chapter also discusses the tasks required of system managers and the tools they use to perform these tasks.
What Is an iIS Process Engine?
An iIS process engine is the heart of an iIS system, shown in Figure 1-1 on page 30 ,
reproduced from the iIS Process Development Guide.
The engine controls and manages business processes from beginning to end, coordinating the work of the different resources that perform the activities defined in each process instance.
At each stage of a process’s execution, the engine evaluates whether an activity is ready to be performed and, if so, assigns that activity to the appropriate resources.
When an activity is completed, the engine routes the work to the next activity or set of activities.
The engine knows how to manage the flow of a process because it is programmed to control and track that process. The program that the engine executes is an iIS process definition. The process definition is created in the iIS Process Definition
Workshop and is then registered with the engine. For information on process definitions, see the iIS Process Development Guide.
27
What Is an iIS Process Engine?
Once a process definition has been registered with the engine, an iIS process client
application (or an application proxy—see Figure 1-1 on page 30 ) can open a session
with the engine and create an instance of the process. The client application or proxy provides any data required to start the process instance, and then the engine takes over. It assigns activities directly to engine sessions or to queues where they can be accessed. Client applications—or applications interacting with the engine through proxies—perform the work required of each activity using whatever application services, enterprise data, or desktop applications necessary, and then notify the engine that the activity has been completed. For information on client applications, see the iIS Process Client Programming Guide. For information about proxies, see the iIS Backbone System Guide.
The relationship of the engine to iIS process client applications, on the one hand, and to the process development workshops, on the other, is illustrated in
Figure 1-1 on page 30 . Client applications maintain sessions with an iIS process
engine to initiate a business process or perform its activities in it. The engine can service a very large number of sessions and manage many instances of many different process definitions. As process definitions (as well as assignment rule dictionaries, user profiles, and a validation) are created or modified in the iIS development environment, they can be registered with the engine, and become the basis for further process execution.
The engine is thus central to an iIS system, implementing business processes that require the performance of many activities by many resources.
28 iPlanet Integration Server • Process System Guide • August 2001
What Is an iIS Process Engine?
Multiple Engine Systems
An iIS system does not need to be limited to a single engine. It can have any number of engines. For example, one engine might be used for testing and another used for production. (see
“Production Engines Versus Development Engines” on page 83 .)
In other cases, organizational considerations or heavy load conditions might require multiple production engines. While engines can communicate with one another—a processes definition that executes on one engine can be invoked as a subprocess by a process definition executing on another—each engine operates independently. A single instance of a process definition executes on only one engine.
In most cases, different process definitions would be executed on different engines.
For example, one process might execute on one engine while a subprocess it invokes might execute on another. If the same process definition is executed on more than one engine (to handle the workload of a large number of client users) then client users would normally be divided up between the engines, each user logging in to only one of the engines.
Multiple engines can run in a single iPlanet UDS environment, or can be spread across a number of connected iPlanet UDS environments. However, there is no mechanism by which one engine can fail over to another. iIS uses a different mechanism to handle engine failover (see
“Failover Configuration” on page 33 ).
Chapter 1 Introduction: iIS Process Management 29
What Is an iIS Process Engine?
Figure 1-1 An iIS Process Management System
Process Develpment
Workshops
Registration
Central
Development
Repository
System Management
Tools
Process Engines
Organization
Database
Engine
Database
Client Applications
TOOL
CORBA/IIOP
C++
ActiveX
JAVA
Application
Services
Engine
Database
Databases
30 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Engine Components
iIS Process Engine Components
As mentioned earlier in this chapter, an iIS process engine is the heart of an iIS system and has been designed to support mission-critical production application systems. The iIS process engine maintains performance under heavy and/or increasing loads and provides automatic recovery in case of unanticipated system failure.
To support both failover and load balancing, the iIS process engine is engineered as a set of interacting application components. These applications work together to provide engine failover protection and the flexibility to handle increasing loads. An iIS engine generally consists of the following application components:
• two engine units
• an engine governor
• a number of database access services
An iIS engine also includes a database that provides storage for persistent state information.
The various engine components are described below in relation to their role in providing failover and load balancing capability. A minimal engine configuration is discussed first, followed by failover and load balancing configurations. To create these configurations, see
“Configuring an Engine” on page 85
.
Minimal Engine Configuration
An iIS process engine consists minimally of three components—an engine unit, a
database service, and a database—as shown in Figure 1-2 . In this configuration, the
engine provides basic functions without failover or load balancing capabilities.
Chapter 1 Introduction: iIS Process Management 31
iIS Process Engine Components
Figure 1-2 Minimal Engine Configuration
Client Applications
Primary
Engine
Unit iIS Process Engine
Database
Service
Engine
Database
Engine Unit The engine unit is an application that performs all the basic iIS engine functions (see
“What Does an iIS Process Engine Do?” on page 36 ). The
engine unit is a single iPlanet UDS server partition containing a number of manager objects (see
). The engine unit, in performing its work, tracks the state of each process, activity, timer, process attribute lock, and session that it creates in the course of process execution. In a typical production situation, the engine unit maintains state information on tens of thousands to millions of objects. It is critical that this state information be kept in a persistent form should the engine unit fail and need to be recovered. For this reason, the engine unit writes all current state information to the engine database (described below).
Database Service The database service is an application that manages the engine unit’s database access. The database service is a single iPlanet UDS server partition that maintains communication channels with the engine unit, opens a session with the engine database, and writes and retrieves state information as required by the engine unit. The database service is a single–threaded application, and can handle only one request to the database at a time. (To see how to overcome this limitation,
see “Full Configuration: Failover and Load Balancing Combined” on page 35 .)
Engine Database The engine database provides persistent storage for state information maintained by the engine. It also stores registration information regarding all process definitions, assignment rule libraries, user profiles, and validations that can be executed by the engine. In addition, the engine database can be used to log historical information for tracking process execution over time. The
32 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Engine Components engine database is not supplied by the iIS product and must be set up independently; however, the engine unit can create all required database tables at startup time. The iIS process engine supports all relational database systems supported by iPlanet UDS (for example, Sybase, Oracle, Informix, and so on).
Failover Configuration
To provide for failover in case the engine unit fails (for whatever reason), a backup engine unit and governor are added to the iIS process engine configuration, as illustrated in
Figure 1-3 Engine Configuration with Failover iIS Process Engine
Client Applications
Governor
Primary
Engine
Unit
Backup
Engine
Unit
Database
Service
Engine
Database
Backup Engine Unit The backup engine unit, a replicate of the engine unit partition, has a unique name that distinguishes it from the primary engine unit.
The primary and backup engine units are partners. The backup engine unit runs in a standby state when the primary engine unit is on line. The two partners know about each other through an open communication channel. If the primary engine unit fails, the backup engine unit comes on line. In that case, the database service
Chapter 1 Introduction: iIS Process Management 33
iIS Process Engine Components opens a channel to the backup unit, which takes over by recovering all the persistent state information stored in the engine database. The new primary engine unit starts process execution at the point where the old primary engine unit left it.
Client sessions with the engine are maintained throughout this failover transition.
NOTE Failover (and recovery of state information) is not instantaneous. In a production system, the state information stored in the engine database can be quite extensive. It includes information on the state of every process instance, the state of every activity and timer in each process instance, the values of process attributes and their lock states, the state of routers and triggers for each activity instance, session activity lists, queue lists, and so on. Accordingly, the amount of time for failover to occur is dependent on the amount of state information in the database and the speed of database access.
Governor The governor is an application that assists in deciding when failover should occur. The governor maintains an open communication channel with both the primary and backup engine units. It uses these channels to determine if a closing of the communication channel between primary and backup engine units is due to engine unit failure or network failure. For example, if the communication channel between the primary and backup engine units closes, but the governor’s communication channel with the primary engine unit remains open, the governor assumes the primary engine unit is still online. However, if neither the governor nor backup engine unit can communicate with the primary engine unit, the governor assumes the primary engine unit has failed, and places the backup engine unit online, making it the new primary engine unit.
(If the primary engine unit has not failed, but cannot communicate with either the governor or backup engine unit, the primary engine unit will drop into STANDBY state, since it has no way of knowing the state of its partner.)
34 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Engine Components
Full Configuration: Failover and Load
Balancing Combined
To deal with heavy loads on the engine and overcome the potential bottleneck of a single database service, additional database services can be added to the failover
engine configuration, as illustrated in Figure 1-4 .
With a heavily loaded engine, large numbers of state changes need to be written to the engine database simultaneously. Database access is likely to be a performance problem. To accommodate large loads, database access is shared among a set of database service components (which may be running on different nodes) using a database service router in the primary engine unit.
Each service is assigned a unique name and allocated a priority (depending, perhaps, on its host node—see
“Engine Component Partitioning” on page 85 ).
When the engine unit needs to access the database, the router provides it the highest priority database access service available. If there are a number of services of equal priority available, the router chooses a database service on a round-robin basis, thus sharing the load among all available services.
Figure 1-4 Engine Configuration with Both Failover and Load Balancing
Client Applications iIS Process
Engine
Governor
Primary
Engine
Unit
Router
Database
Services
Services
Services
Backup
Engine
Unit
Engine
Database
Chapter 1 Introduction: iIS Process Management 35
What Does an iIS Process Engine Do?
What Does an iIS Process Engine Do?
As suggested in “What Is an iIS Process Engine?” on page 27 , an iIS process engine
performs a number of different functions in support of an iIS system. These include the following.
Managing sessions The engine opens, suspends, and closes sessions. When opening a session, the engine first validates a user’s logon against an organizational database. For more information on sessions, see
“Engine Sessions” on page 158 .
Executing processes The engine creates instances of a process and manages their execution from start to finish. During each process’ execution, a succession of activities is performed by applications that have opened sessions with the engine.
The engine manages and tracks these activities through to their final completion.
Registering distributions Process definitions, assignment rule dictionaries, user profiles, and a validation constitute the process logic components executed by the engine during process execution. Registration lets you change these components dynamically as business processes and organizational structures change.
Maintaining an engine history database The engine can maintain a history of each process execution, writing all changes of state to an engine history database.
The history can include changes of state in activities, process attributes, timers, and so on.
While process execution is the key engine function, managing sessions, registering definitions, and maintaining the history database are all necessary to support process execution.
To provide these functions, the iIS engine is internally structured around a number of manager objects, as shown in
• Session Manager—maintains engine sessions
• Process Manager—works closely with the Timer Manager and Access Manger to execute iIS process definitions
• Registration Manager—keeps track of the names and versions of registered process definitions
• History Manager—writes current state and history log information to the engine database.
36 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Management Tasks
Figure 1-5 Engine Manager Objects
Engine Unit
Engine
Object
Session
Manager
Process
Manager
Registration
Manager
History
Manager
Timer
Manager
Access
Manager Database
Service
iIS Process Management Tasks
iIS process management tasks can be grouped into four broad categories:
• setting up and maintaining an iIS process system
• managing iIS process engines
• managing registration of process definitions
• managing process execution
Each of these categories is discussed briefly below and treated in detail in the corresponding chapter of this system management guide.
Setting up and Maintaining an iIS System
Setting up a new iIS process management system—whether used for development, testing, production, or a combination of the three—involves a number of basic tasks, described below.
Chapter 1 Introduction: iIS Process Management 37
iIS Process Management Tasks
Setting Up an iPlanet UDS Runtime Environment
An iIS process management system runs in an iPlanet UDS software environment.
Both the development and production capabilities of iIS (both process development and process execution) use the distributed runtime services provided by an iPlanet UDS environment. A functioning iPlanet UDS environment is the technical infrastructure underlying an iIS process management system.
Installing iIS Process Management Software
iIS process management system software consists of a number of client and server software modules required to support nodes that perform a number of different functions. The functionally different types of nodes in an iIS process system are the following:
• nodes that support iIS process engine components
• nodes that support process development
• nodes that support client application development or client application execution in a production environment
Before installing iIS process system software, you must first determine which nodes in your iPlanet UDS environment are used for each of these purposes and to install the corresponding system software on each.
When upgrading iIS process system software, especially in production environments, you might have to migrate data from existing iIS process engine databases to new ones. See
“Upgrading an iIS System” on page 63 .
Setting Up and Maintaining Central Development Repositories
In iIS development environments, the code created in the process development workshops is stored in a modified iPlanet UDS central development repository. As an iIS system manager, you may be called on to create iIS central development repositories and start a Repository Server for each. (Developers can also use private iIS repositories.)
Central development repositories require maintenance, such as backing them up periodically, compacting them regularly, and implementing usage patterns among your development staff that improves performance.
For more information on managing central development repositories, see the
iPlanet UDS System Management Guide.
38 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Management Tasks
Managing iIS Process Engines
Care must be taken to make sure that each iIS process engine is set up and performing properly. Managing engines consists of the following tasks:
• configuring engines
• starting up and shutting down engine components
• monitoring and changing the state of an engine
• reconfiguring an engine to accommodate increased load, improve performance, or recover from failure
• managing engine databases
Managing Registration
An iIS process engine executes process logic created in the process development workshops: process definitions, assignment rule dictionaries, and a user profile.
These software components need to be registered with the engine so they can be dynamically loaded by the engine and used in process execution.
As a system manager, you have to regularly register new or updated process definitions (or assignment rule dictionaries or a user profile) with an engine, and possibly unregister them when they become obsolete.
Managing Process Execution
In executing process definitions, the engine creates instances of each process definition and coordinates their execution from start to finish. During process execution, a succession of activities specified by the process definition is performed by client application that have opened sessions with the engine. The engine manages and tracks these activities through to their final completion, ensuring that they are performed in proper sequence.
Chapter 1 Introduction: iIS Process Management 39
iIS Process Management Tools
Managing process execution involves monitoring the activity of the engine and making administrative adjustments when necessary. The specific tasks include:
• monitoring engine sessions, and suspending or terminating sessions when necessary
• monitoring the number of process instances being executed by an engine at any time
• monitoring execution of individual processes, looking for bottlenecks or failures, and aborting or resetting particular process activities, as necessary
• providing historical analysis of process execution activity
iIS Process Management Tools
iIS includes two system management tools: the iIS Console and its command line counterpart, Conductor Script. These tools provide an interface to system management agents in the iPlanet UDS runtime environment and in the iIS process engine for managing engines and process execution.
iPlanet UDS also provides a separate set of command-line tools for managing development repositories.
This section briefly describes the iIS process management tools.
iIS Console
The iIS Console application provides a graphical user interface for performing most of the system management tasks discussed in
. You use the iIS Console to manage iIS engines (including registering process definitions, and so on), manage individual process instances, and monitor overall process execution activity.
Most system management procedures explained in this guide assume that you are using the iIS Console. For an introduction to the iIS Console, see
40 iPlanet Integration Server • Process System Guide • August 2001
iIS Process Management Tools
Conductor Script Utility
The Conductor Script utility is the functional equivalent of the iIS Console application, but with a command-line interface. You can perform any of the functions using Conductor Script commands that you can perform in the iIS
Console, but you can also incorporate these functions into scripts for execution at specified times.
For more information on the Conductor Script utility, see
Custom System Management Tools
In an iPlanet UDS development environment you can use the iPlanet UDS development workshops to write your own system management tools exercising the same system management agents utilized by the iIS Console and the Conductor
Script utility. These custom tools allow you to automate regular system management tasks or respond automatically to particular state conditions in an engine.
Repository Management Tools
iPlanet UDS provides several command-line tools for creating ( rpcreate
), copying
( rpcopy
), starting ( rpstart
), stopping ( rpstop
), and compacting ( rpclean
) central development repositories and Repository Servers.
For more information on repository management tools, see the iPlanet UDS System
Management Guide.
Dump/Restore Facilities
iIS provides facilities for dumping the information in an engine database to an
ASCII file. These facilities—a Dump/Restore graphical user interface application and an equivalent command-line utility—are used to restore an engine database in iIS upgrades in which the engine database schema is changed. For more
information on the Dump/Restore utilities, see “Dumping and Restoring Data” on page 126 .
Chapter 1 Introduction: iIS Process Management 41
iIS Process Management Tools
42 iPlanet Integration Server • Process System Guide • August 2001
Chapter 2
Setting Up an iIS Process
Management System
Setting up an iIS process management system—whether for development, testing, production, or a combination of the three—is the first task you must perform as an iIS process system manager.
System setup involves determining which nodes in your environment support the different components of your iIS process system, and then installing the appropriate iIS software on each of these nodes.
Since iIS runs on top of a functioning iPlanet UDS environment, you may have to set up an iPlanet UDS environment before setting up your iIS process system.
This chapter explains how to set up an iIS process system, and covers the following topics:
• setting up an iPlanet UDS runtime environment
• components of an iIS process system
• setting up an iIS process system
• maintaining an iIS process system
For information on how to configure and start an iIS process engine, refer to
Chapter 4, “Managing Engines.”
43
Preparation: Setting up an iPlanet UDS Runtime Environment
Preparation: Setting up an iPlanet UDS
Runtime Environment
An iIS process system runs in an iPlanet UDS software environment. Both the development and runtime capabilities of iIS (process development and process execution) use the distributed runtime services provided by an iPlanet UDS environment. A functioning iPlanet UDS runtime system (including a central development repository for iIS process development) is the technical infrastructure underlying an iIS process system.
Consequently, you must have a functioning iPlanet UDS environment before setting up an iIS process system. This section introduces some of the important considerations for setting up an iPlanet UDS environment. For detailed information on how to set up an iPlanet UDS environment, consult the iPlanet UDS
System Management Guide. iPlanet UDS system software is designed to be environment independent.
Nevertheless, iPlanet UDS software has critical dependencies on the specific versions of operating systems, window systems, networking systems, runtime libraries, and database management systems used at your site. One of the most important aspects of properly setting up an iPlanet UDS environment is to make sure that the physical environment (hardware and software) meets iPlanet UDS system requirements. For more information on these requirements, see the iPlanet
UDS System Installation Guide.
While iPlanet UDS system software is usually installed in an existing network configuration, you should consider how to best use the available resources, depending on the type of environment you are setting up.
If the environment is principally an iPlanet UDS or iIS development environment, then the locations of your central development repositories (Repository Servers) and Environment Manager service are key considerations.
If the environment is principally a production environment for mission-critical applications, then the availability and locations of vital application resources (such as database management systems and C program libraries) and the speed and reliability of servers are some key considerations. These considerations might also influence where you place the Environment Manager service.
In general, when setting up an iPlanet UDS environment, you first install iPlanet
UDS on a node that plays the role of a central server. Typically, this node hosts the
Environment Manager service and the Repository Server and often serves as a central distribution node for installing iIS on other nodes in your environment.
After you install iPlanet UDS on your central server, you install iPlanet UDS on other nodes in the environment.
44 iPlanet Integration Server • Process System Guide • August 2001
iIS Process System Components
The iPlanet UDS installation program creates an iPlanet UDS directory structure and source files on your target node, sets a number of environment variables used by iPlanet UDS at startup time, and creates startup scripts for starting the appropriate system management service—the Environment Manager or Node
Manager—for your target node.
Setting up an iIS process system, in turn, depends upon the iPlanet UDS system management services provided in an iPlanet UDS environment.
iIS Process System Components
An iIS process system consists of both development and runtime components, as illustrated in
Figure 2-1 , and described in the iIS Process Development Guide.
The system includes one or more iIS process engines, which are accessed by a number of iIS process client applications. An engine controls and manages the flow of business processes, coordinating the work of the different client applications that perform the activities that make up these processes. The client applications perform activities directly or by invoking other application services in a distributed application.
An iIS process engine executes process definitions created by developers using a set of graphically-based process development workshops. These workshops store information in a central development repository. When development of a process definition is complete, the process definition is dynamically registered with an engine, which can then execute the process on behalf of a number of applications.
These applications can be client applications that directly call the engine, or applications that are integrated using the iIS backbone.
Chapter 2 Setting Up an iIS Process Management System 45
iIS Process System Components
Figure 2-1 Components of an iIS Process System
Process Develpment
Workshops
Registration
Central
Development
Repository
System Management
Tools
Organization
Database iIS Process Engines
Primary
Engine
Unit
Governor
Database
Service
Service
Service
Backup
Engine
Database
Client Applications
TOOL
CORBA/IIOP
C++
ActiveX
JAVA
Application
Services
Engine
Database
Databases
The components of an iIS process system, shown in Figure 2-1
, are implemented through a number of software modules running on various nodes in your computing environment. Some of the components are provided by iIS system software (iIS process engine components, process development workshops, and system management tools). Some must be developed on site and require iIS system software (process definitions and iIS process client applications). Others must be developed on-site using other software products (organization database).
46 iPlanet Integration Server • Process System Guide • August 2001
iIS Process System Software
To set up an iIS process system, install the iIS system software modules that support development on your development nodes. Then install the iIS runtime modules on the nodes on which you will be executing your distributed enterprise applications.
iIS Backbone
If you are integrating applications with the iIS Backbone, also install the iIS runtime. For more information, refer to the iIS Installation Guide. For management functions specific to the iIS Backbone, refer to the iIS Backbone System Guide.
iIS Process System Software
iIS process system software consists of a number of software modules that provide—or are used to develop and manage—many of the iIS process system components illustrated in
. These modules, organized by functional category, are described in the following table. The table also indicates which system software modules are marked for use as compiled partitions.
Table 2-1 Process System Software Modules
Software Module Category Description
WFEngineUnit
(compiled)
Engine component
The server application that performs all the basic iIS engine functions (see
“What Does an iIS Process Engine Do?” on page 36 ). Consists
of a single iPlanet UDS server partition.
Needed on engine server nodes.
WFGovernor
(compiled)
WFDatabaseSvc
(compiled)
Engine component
Engine component
The server application that assists in deciding when failover of an engine unit should occur
(see “Governor” on page 105 ). Consists of a
single iPlanet UDS server partition. Needed on engine server nodes.
The server application that manages the engine unit’s database access (see
Service” on page 109 ). Consists of a single
iPlanet UDS server partition. Needed on engine server nodes.
Chapter 2 Setting Up an iIS Process Management System 47
iIS Process System Software
Table 2-1 Process System Software Modules (Continued)
Software Module Category Description
WFLibrary
(compiled)
WFModel
(compiled)
WFAccessServiceObj
(compiled)
WFClientLibrary
(compiled)
WFProcMgrLibrary
WFAdminLibrary
Process development
Process development
Process development
TOOL client application development
TOOL client application development
TOOL client application development
A library distribution that supports the process development workshops. Needed in iIS process development repository and on process development nodes.
A library distribution that provides repository schema definitions used to create code in the process development workshops. Needed in iIS process development repository and on process development nodes.
A library distribution that provides code used in the process development workshops for accessing iPlanet UDS service objects from within activity and router methods. Needed in iIS process development repository and on engine server nodes.
A library distribution that provides the API for process client applications written in the iPlanet UDS TOOL language. Needed in client application development repository, on TOOL client application development nodes, and on runtime nodes running client applications.
A library distribution that provides the limited process management API for process client applications written in the iPlanet UDS TOOL language. Optionally used in client application development repository, on TOOL client application development nodes, and on runtime nodes running such client applications.
A library distribution that provides the limited process execution monitoring API for process client applications written in the iPlanet UDS
TOOL language. Optionally used in client application development repository, on TOOL client application development nodes, and on runtime nodes running such client applications.
48 iPlanet Integration Server • Process System Guide • August 2001
iIS Process System Software
Table 2-1 Process System Software Modules (Continued)
Software Module Category Description
WFClientAPI
(compiled)
WFCORBAapi
(compiled)
WFConsole
WFScript
WFDrWind
WFDrDump
WFDrRest
OFCustomIF
(compiled)
WFCustomIF
(compiled)
C++ client application development
Java/IIOP client application development
System
Management
System
Management
Engine
Database
Dump/Restore application
Engine
Database
Dump utility
Engine
Database
Restore utility
System
System
A DLL required to write process client application code in C++. Needed on C++ client application development nodes, and on runtime nodes running C++ client applications.
A server application (CORBA interface service) required to execute process client application code written in JAVA/IIOP.
Needed on at least one server node in the iIS environment, normally the central server or an engine server.
A GUI client application for performing iIS process management system tasks. For details,
see Chapter 3, “The iIS Console.”
A command-line client application for scripting iIS system management tasks. For details, see
Chapter 8, “Using the Conductor
A graphical user interface application used for dumping engine database tables to a file and for restoring data to an engine database. For details, see
“Dumping and Restoring Data” on page 126 .
A standalone program that dumps the engine state and history data to files. For details, see
“Dumping Database Tables” on page 126
.
A standalone program that restores the data from files generated using WFDrDump to an
engine database. For details, see “Restoring
Database Tables” on page 131 .
A library distribution that provides “interface glue” between a client application, engine, and user profile. Needed in iIS development repositories, on engine server nodes, and on process client application development nodes.
Extension of OFCustomIF.
Chapter 2 Setting Up an iIS Process Management System 49
iIS Process System Software
Table 2-1 Process System Software Modules (Continued)
Software Module Category Description
WFEnvDefinition
(compiled)
WFEnvAgent
(compiled) en_us.cat
WFSeed.btx
WFSeed.btd
System
System
System
Development workshops
A library distribution that provides underlying system management support for accessing iIS process engines and performing registration of process definitions. Needed on all nodes.
An application that supports generation and deployment of library distributions for registration of process definitions, assignment rule dictionaries, and user profiles. Needed on central server node.
A message catalog used in translating all language strings in the product.
A base development repository that contains all the class definitions needed to create process definitions or TOOL client applications. Needed on repository server nodes.
Compiled and Interpreted Engine Components
There is a script for alternating between the use of compiled or interpreted engine components. This is useful if exceptions occur when you are running an engine in compiled mode; you can switch to interpreted mode to obtain trace back on exceptions. The platform-specific script, which is installed in
FORTE_ROOT/install/bin, is the following:
Script Name setccomp.sh
setccomp.bat
setccomp.com
Platforms
All UNIX
Types of Script
Bourne-shell
MS Windows NT MS-DOS batch file
Alpha VMS, VAX/VMS VMS command procedure
Syntax: setccomp.sh
TRUE | FALSE
TRUE specifies compiled partitions; FALSE specifies interpreted partitions.
50 iPlanet Integration Server • Process System Guide • August 2001
iIS Process System Software
➤
Before you invoke the setccomp script, you must do the following
1.
Set the FORTE_ROOT environment variable to point to a valid iIS installation.
2.
Install the following iIS library distributions in the iPlanet UDS development environment:
3.
❍
❍
WFGovernor
WFEngineUnit
❍
WFDatabaseSvc
Start the iPlanet UDS Environment Manager on the server node where you invoke the script.
iIS Process System Configuration
Setting up an iIS process system involves a bit of system design work. You must decide in advance, for example, which nodes in your computing environment host the various iIS process system components shown in
In particular, you must decide which node or nodes in your environment support the following functions:
• running iIS process engine components
• developing process definitions
• developing iIS process client applications
• hosting iIS system management tools
• running the iIS central development Repository Server
• running iIS process client applications
All but the last of these functions require iIS process system software. In setting up an iIS process management system, these are the components that are the focus of attention.
For purposes of discussion, an example iIS process system configuration is shown
. Seven distinct kinds of iIS nodes are shown:
Central server The iPlanet UDS central server node in your environment. It hosts the iPlanet UDS Environment Manager (including Name Service) and one or more unique iIS services (such as the WFEnvAgent service).
Chapter 2 Setting Up an iIS Process Management System 51
iIS Process System Software
Repository server A server node (runs an iPlanet UDS Node Manager) that hosts the iIS central development repository and repository service.
Engine server A server node (runs an iPlanet UDS Node Manager) that hosts one or more engine components of one or more engines. One of the engine servers typically hosts an engine database. (Putting the engine database and the engine server on separate nodes is generally not recommended for performance reasons.)
Process development A node on which process developers (using the process development workshops) create the process definitions that are executed by iIS process engines.
Client application development A node on which client application developers create the process client applications that communicate with the iIS engine and perform the activities specified in process definitions.
System management A node used by a system manager to manage an iIS process system.
Runtime client A node that runs an iIS process client application, but which cannot be used for development.
While conceptually it is easier to think of each of these nodes as distinct, in reality there is no reason why some of the functions described could not be combined and performed on a single node. (In fact, you could run the whole system on a single node.)
For example, process development and client application development could both be performed on the same client node, or each could be performed on an engine server node that supports a windowing system. Deciding where these components are installed depends principally on who performs the various iIS development and system management tasks.
Also, the central server, which plays a unique role in an iIS system, can both host the central development repository and serve as an engine server node, supporting one or more iIS process engine components. Application servers in your iIS process system can also host iIS engine components. Choosing which components to install on which servers depends on the resources available on each server and the requirements of each component.
52 iPlanet Integration Server • Process System Guide • August 2001
iIS Process System Software
Figure 2-2 iIS Process System Configuration
Process Development
Process
Development
Workshops
Central Server
Environment
Manager
Client Application
Development
Client API
Repository Server
Repository
Service
Engine Server
System Management
Tools
Conductor
Console Engine
Components
Runtime Applications
Application Servers
Central
Development
Repository
Engine
Database
Enterprise
Database
Application
Services
You do not have to decide at iIS installation time exactly which engine components to assign to each server node because all component partitions are installed on each server node that supports an engine. You select which components to start on any node when you configure each engine (see
“Configuring an Engine” on page 85
).
Chapter 2 Setting Up an iIS Process Management System 53
iIS Process System Software
For the purpose of system setup, the primary considerations are that the iIS process engine is the workhorse of your iIS process system and that it accesses a potentially very large database. Your engine server node or nodes should therefore be a very high performance server with plenty of available memory. If you are unsure at this point how to configure your iIS engine, designate all likely nodes as engine server nodes. This approach gives you the most flexibility later on.
Another design issue concerns the iIS development repository. You might want iIS developers to use an existing iPlanet UDS repository, or you might prefer to create one or more central development repositories for exclusive use by iIS developers.
In addition, you might decide that the repository server needed to support iIS development should reside on a server other than the central server node hosting the Environment Manager, as shown in
In any case, before beginning your iIS setup procedure, fill in a table similar to the one that follows: iIS Function Node type: Server/Client
Central server
Repository server
Engine servers
Process development
Client application development
Server
Server
Server
Client or server
Client or server
System management Client or server
Runtime client application Client or server
Node Names
54 iPlanet Integration Server • Process System Guide • August 2001
Setting Up an iIS Process System
Setting Up an iIS Process System
After you have decided how to configure your iIS process system (and filled out the table in the previous section), you are ready to set up your system.
To set up an iIS process system, run the platform-specific iIS installation program on each node requiring iIS process system software. The software components installed by the program depend on whether the target node is a central server node, engine server node, client development node (process development or client application development), or runtime client.
Because the iIS installation program depends on services provided by an iPlanet
UDS runtime system, you must set up a functioning iPlanet UDS runtime environment if you do not already have one at your site. (See
“Preparation: Setting up an iPlanet UDS Runtime Environment” on page 44 .)
iIS Process System Setup Procedure
The following general procedure should be followed in setting up an iIS process system.
➤
To set up an iIS process system
1.
Make sure that you have a functioning iPlanet UDS environment that includes all the server and client nodes required to support your iIS process system.
2.
3.
4.
5.
6.
Run the iIS installation program on your iPlanet UDS central server node.
Run the iIS installation program on all iIS engine server nodes.
Run the iIS installation program on all iIS client nodes (process development and/or client application development nodes).
On all development nodes, set the FORTE_REPOSNAME environment variable to the name of your iIS Repository Server. (You can use the iPlanet
UDS Control Panel—see the iPlanet UDS System Management Guide for more information.)
Configure and start your iIS process engine or engines. (See
)
Chapter 2 Setting Up an iIS Process Management System 55
Setting Up an iIS Process System
7.
After process client applications have been developed, run the iIS installation program on all runtime client nodes (those nodes that support an iIS process client application but do not support development).
8.
In sites developing or running process client applications using the
CORBA/IIOP interface to the iIS engine, start the CORBA/IIOP interface service using the IIOPServer Conductor Script command (see
This setup procedure creates a functioning iIS process system in which developers can create process definitions and register them with an iIS engine and then develop process client applications and use them to perform the activities of an executing process instance.
CAUTION An iIS process system can only function in the iPlanet UDS environment in which it has been set up. For example, you cannot change the name of your iPlanet UDS environment—even if the physical environment remains the same—and still have a functioning iIS process system.
The iIS Installation Program
The setup procedure described in the previous section makes extensive use of the iIS installation program. The iIS installation program has four main installation options: central server node, engine server node, development client node, and runtime client node. Each installs, by default, the iIS system software appropriate for that type of node, and provides customizing options (such as installing iIS process management tools), as well.
This section describes what the installation program does on each of the following four node types:
• central server
• engine server
• client development (process development or client application development)
• runtime client
For platform-specific information and installation program details, see the iIS
Installation Guide.
56 iPlanet Integration Server • Process System Guide • August 2001
Setting Up an iIS Process System
Central Server Installation
On a central server node—the first node to be installed in an iIS system—the iIS installation program performs the operations described in the following table:
Operation Software Module
Prepares node as the central distribution node for all distributions.
Loads distributions into environment repository to enable deployment by iPlanet UDS system management agents.
Transfers iIS repository files to node.
All application distributions
All library distributions
All server application distributions
All library distributions
WFSeed.btx
WFSeed.btd
Creates iIS repository server.
Installs engine components.
Installs process development libraries.
Installs iIS TOOL client development libraries.
Installs iIS C++ client development DLL.
Installs CORBA/IIOP interface service.
Installs iIS process management client applications.
Installs iIS system libraries.
Installs registration support service.
Installs message catalog file
WFEngineUnit
WFGovernor
WFDatabaseSvc
WFLibrary
WFModel
WFAccessServiceObj
WFClientLibrary
WFProcMgrLibrary
WFAdminLibrary
WFClientAPI
WFCORBAapi
WFConsole
WFScript
OFCustomIF
WFCustomIF
WFEnvDefinition
WFEnvAgent en_us.cat
Installs Dump/Restore facilities WFDrWind
WFDrDump
WFDrRest
FORTE_ROOT directory appdist
—— install/respos cpy repos userapp userapp userapp userapp userapp userapp userapp userapp install/nls/co nductr userapp
Chapter 2 Setting Up an iIS Process Management System 57
Setting Up an iIS Process System
Engine Server Installation
On an engine server node, which must be installed after the central server node, the iIS installation program performs the operations described in the following table:
Operation
Transfers iIS repository files to node.
Installs engine components.
Installs process development libraries.
Installs iIS TOOL client development libraries.
Software Module
WFSeed.btx
WFSeed.btd
WFEngineUnit
WFGovernor
WFDatabaseSvc
WFLibrary
WFModel
WFAccessServiceObj
WFClientLibrary
WFProcMgrLibrary
WFAdminLibrary
WFClientAPI
FORTE_ROOT directory install/resposcpy userapp userapp userapp userapp Installs iIS C++ client development
DLL.
Installs iIS system management client applications.
Installs iIS system libraries.
Installs message catalog file
Installs Dump/Restore facilities
WFConsole
WFScript
OFCustomIF
WFCustomIF
WFEnvDefinition en_us.cat
WFDrWind
WFDrDump
WFDrRest userapp userapp install/nls/conductr userapp
58 iPlanet Integration Server • Process System Guide • August 2001
Setting Up an iIS Process System
Development Client Installation
A development client node can be used for either process development or client application development. On a development client node, which must be installed after the central server node, the iIS installation program performs the operations described in the following table:
Operation Software Module
Transfers iIS repository files to node.
Installs process development libraries.
Installs iIS process management client applications.
Installs iIS system libraries.
WFSeed.btx
WFSeed.btd
WFLibrary
WFModel
WFAccessServiceObj
Installs iIS TOOL client development libraries.
WFClientLibrary
WFProcMgrLibrary
WFAdminLibrary
Installs iIS C++ client development DLL.
WFClientAPI
WFConsole
WFScript
Installs message catalog file
OFCustomIF
WFCustomIF
WFEnvDefinition en_us.cat
FORTE_ROOT directory install/resposcpy userapp userapp userapp userapp userapp install/nls/conductr
Chapter 2 Setting Up an iIS Process Management System 59
Setting Up an iIS Process System
Runtime Client Installation
On a runtime client node, which must be installed after the central server node, the iIS installation program performs the operations described in the following table:
Operation
Installs iIS TOOL client libraries.
Installs iIS C++ client development DLL.
Installs iIS process management client applications.
Installs iIS system libraries.
Installs message catalog file
Software Module
WFClientLibrary
WFProcMgrLibrary
WFAdminLibrary
WFClientAPI
WFConsole
WFScript
OFCustomIF
WFCustomIF
WFEnvDefinition en_us.cat
FORTE_ROOT directory userapp userapp userapp userapp install/nls/conductr
Configuring and Starting Your iIS Engines
When your iIS process system software is installed on the various nodes in your environment (including an iIS central development repository), an iIS application system designer can begin implementing the various design elements, process developers can begin creating process definitions, and client application developers can begin writing iIS client applications.
However, before long it will be necessary to have a test engine running in your environment. Configuring and starting an iIS process engine requires familiarity
with iIS process management tools (see Chapter 3, “The iIS Console” ) and is
described fully in
Chapter 4, “Managing Engines.”
60 iPlanet Integration Server • Process System Guide • August 2001
Maintaining an iIS Process System
Maintaining an iIS Process System
Once your iIS process system is set up and functional (including configuration and startup of engines, as discussed in
), there are relatively few maintenance tasks that you need to perform.
Most maintenance concerns the databases in the system. For example, you need to regularly back up the central development repository as well as compact it from time to time (see the iPlanet UDS System Management Guide for more information).
Also the engine database must be monitored to make sure you do not run out of disk space.
Other maintenance tasks might include the following:
• adding new nodes to an iIS system
• moving an iIS process engine
• creating a new iIS Repository Server
• moving an iIS Repository Server
• creating a private iIS repository
• uninstalling an iIS system
Each of these are discussed briefly below.
Adding New Nodes to an iIS System
➤
To add a new node to an iIS system
1.
Decide which function the new node is to perform in your iIS system.
2.
Run the iIS installation program and choose the appropriate installation option.
Chapter 2 Setting Up an iIS Process Management System 61
Maintaining an iIS Process System
3.
Choose default or custom installation, depending on the components you want to install on the node.
NOTE If you know the application or library distributions required for the
new node (see Table 2-1 on page 47 ), you can install them using
iPlanet UDS system management services rather than the iIS installation program. The distributions can be installed on the new node using Escript or the iPlanet UDS Environment Console, depending on whether the new node is a client or server, as described in the iPlanet UDS System Management Guide.
Moving an iIS Engine
Moving an iIS engine or engine component is straightforward. You move the engine or engine component to a different engine server node by reconfiguring the engine as described in
“Configuring an Engine” on page 85 . If the target node is
not presently an engine server node, install iIS system software on the target node using the instructions in
“Adding New Nodes to an iIS System” on page 61
.
Creating a New iIS Repository Server
➤ To create a new iIS Repository Server
1.
Decide which node is to host the new repository server.
2.
Run the iIS installation program and choose the Engine Server option.
3.
4.
5.
Choose Custom Installation.
Check Create iIS Repository and clear all other options.
Click OK and follow the screen questions and instructions.
Moving an iIS Repository Server
➤
To move an iIS Repository Server
1.
Select a server node to host the relocated repository server.
2.
Shut down the current Repository Server.
62 iPlanet Integration Server • Process System Guide • August 2001
Maintaining an iIS Process System
3.
4.
Move the two iIS repository files (reposname.btx and reposname.btd) from
FORTE_ROOT/repos on the original Repository Server node to the same location on the target node.
Modify the iPlanet UDS startup script on the server to include the rpstart command needed to start the iIS repository server (see the iPlanet UDS System
Management Guide).
Creating a Private iIS Repository
➤
To create a private iIS Repository on a development node
1.
Copy the two repository seed files (wfseed.btx and wfseed.btd) from
FORTE_ROOT/resposcpy to FORTE_ROOT/repos.
2.
3.
Rename the two files to correspond to the name of your iIS private repository.
You might have to modify the files to provide read/write access.
Edit the iPlanet UDS Distributed or iPlanet UDS Standalone system icons that start iIS.
Set the -fr flag in the icon’s command line to reference the new private repository. For more information, refer to instructions about starting the process development environment in the iIS Process Development Guide.
Upgrading an iIS System
Upgrading an iIS system is generally straightforward: You install the new version of iIS system software over the older version. Engine configuration files can be used with the new version, though you might want to reconfigure engines to make use of new engine configuration options.
The situation in which you must exercise caution, however, is if you have state or history information in your engine database that you need to preserve across the upgrade. If the engine database schema changes from the older version to the newer version of iIS, you must migrate that data from the older database schema to the new one. iIS provides Dump/Restore facilities to use for this purpose. See
“Dumping and Restoring Data” on page 126
, and be sure to check all release notes.
Chapter 2 Setting Up an iIS Process Management System 63
Maintaining an iIS Process System
Uninstalling an iIS System
Because iIS server software is installed using iPlanet UDS system management services, the iPlanet UDS environment repository has a record of all engine components installed on servers in your environment. To uninstall an iIS system, first use iPlanet UDS system management tools (Environment Console or Escript) to uninstall these components from the environment.
In addition, uninstalling an iIS system requires removing the various iIS system software components from the various nodes on which they have been installed.
The components—application partitions and libraries—are installed in a standard iPlanet UDS location on each node: FORTE_ROOT/userapp/distribution_ID, where distribution_ID is the name of the software module. (For the names of the
software modules installed on each type of node, see “The iIS Installation
To revert a repository to a non-iIS development repository, you need to delete all the libraries imported by the iIS installer. After deleting the WFLibrary distribution from FORTE_ROOT/userapp, the iIS-specific buttons and menus are removed from the Repository Workshop, and no longer appear on startup.
64 iPlanet Integration Server • Process System Guide • August 2001
Chapter 3
The iIS Console
This chapter describes the iIS Console, the iIS product’s window-based tool for performing iIS process management tasks.
This chapter assumes that you have set up an iIS process management system and have installed iIS process management applications (iIS Console and Conductor
Script) on at least one node in your environment.
This chapter covers the following topics:
• overview of the iIS Console
• starting the iIS Console
• using the iIS Console window
• navigating to other iIS Console windows
• summary of menu commands
Overview
The iIS Console is the main system management application for performing iIS process management tasks. The iIS Console has a graphical user interface, as opposed to Conductor Script, which has a command line interface.
NOTE Neither the iIS Console or Conductor Script can be used to perform backbone system management tasks. For information on backbone system management, refer to the iIS Backbone System Guide.
65
Overview
The iIS Console is used for the following four general kinds of iIS process management tasks:
• configure and manage process engines
The iIS Console provides a set of windows that let you configure a new iIS engine, start and view the status of an already configured engine, and reconfigure an existing engine, if necessary.
• manage registration
You can register a number of process logic components created in the iIS process development workshops with one or more iIS engines. When these software components are registered, they can be dynamically loaded by an engine and used in process execution.
• manage process execution
Using the iIS Console, you can monitor the activity of an engine and make administrative adjustments when necessary. You can monitor engine sessions and send messages to client applications, and you can monitor the engine’s execution of individual processes.
• monitor alarms and diagnostic messages
You can monitor high priority events (alarms) from within the iIS Console, as well as view diagnostic messages generated by engine components. All these alarms and messages are useful in troubleshooting problems in engine performance and process execution.
The iIS Console connects to and communicates with the executing iPlanet UDS
Environment Manager and any active Node Managers in your iPlanet UDS environment. It gives you access to iIS engine agents: objects that control engine components and provide information about process execution.
NOTE The Conductor Script command line utility is functionally equivalent to the iIS Console. However, all procedural instructions in this guide assume you are using the iIS Console. For information on Conductor Script, see
66 iPlanet Integration Server • Process System Guide • August 2001
Starting the iIS Console
Starting the iIS Console
You can start the iIS Console on any node in your iPlanet UDS environment where it has been installed.
➤
To start the iIS Console on Windows or Windows NT
1.
Double-click the iIS Console icon.
2.
).
➤ To start the iIS Console on UNIX, OpenVMS, or Windows NT
1.
Use the cconsole
command (see “Using the cconsole Command”
below for information).
2.
).
When the iIS Console starts, it opens the iIS Console main window shown in
Using the cconsole Command
As mentioned above, you start the iIS Console on command-line-based operating systems by executing the cconsole
command.
The syntax of the cconsole command for most platforms: cconsole [-fl log_flags][-fm memory_flags]
The syntax of the cconsole command for OpenVMS:
VFORTE CCONSOLE
[/LOGGER=log_flags]
[/MEMORY=memory_flags]
As in all iPlanet UDS command line specifications, if you use a name that includes a space, you should enclose the name in double quotation marks.
Chapter 3 The iIS Console 67
The iIS Console Main Window
The following table describes the command line flags for the cconsole
command.
Flag
-fl log_flags
/LOGGER=log_flags
-fm memory_flags
/MEMORY= memory_flags
Description
Specifies the log flags to use for the iIS Console session. See the
iPlanet UDS System Management Guide for information about the syntax for specifying log flags. Overrides the
FORTE_LOGGER_SETUP environment variable setting. On
UNIX, you must specify the log flags in double quotes.
Specifies the memory flags to use for the iIS Console session.
See the iPlanet UDS System Management Guide for syntax information. Overrides defaults appropriate for the operating system. On UNIX, you must specify the memory flags in double quotes.
The iIS Console Main Window
The iIS Console main window is a view of configured iIS process engines in your active environment. In the main window, you can initiate all system management tasks you want to perform in your iIS process system. You can use the main window to manage engines, registrations, and process execution in your environment. You can also add password protected access to iIS Console.
The iIS Console main window consists of two areas: the main viewing panel and the menu bar.
68 iPlanet Integration Server • Process System Guide • August 2001
Active environment
Engines
Figure 3-1 iIS Console Main Window
Menu bar
The iIS Console Main Window
Popup menu
Main viewing panel
Main Viewing Panel
The main viewing panel displays all configured engines in an iPlanet UDS environment. Engines are shown with icons representing the state of each engine:
Off
Transition
Online
Error state
Engine is configured but has not been started.
Engine is in the process of starting up or shutting down.
Engine has fully started and is online.
Engine has encountered an exception while attempting to start.
Most tasks you perform using the iIS Console are initiated by first selecting an engine from the main viewing panel and then selecting the desired operation from the appropriate menu.
Chapter 3 The iIS Console 69
The iIS Console Main Window
Menu Bar
The iIS Console menu bar provides all the commands you can execute from the main window. The menus are summarized below, and a full list of the commands is provided at the end of this chapter.
The main window menus are:
Environment menu Provides environment-wide iIS Console commands (such as for registrations), or general commands such as opening a window to see alerts being generated from iIS process engines.
View menu Provides commands for setting refresh properties of the window.
Engine menu Provides engine management commands for configuring, starting up, viewing the status of, deleting, performing logging and trace functions, and shutting down an iIS engine.
Monitor menu Provides commands for monitoring and managing processes being executed by an iIS engine, verifying registrations, and charting performance.
Help menu Provides online Help for the iIS Console.
Mouse Popup Menu
iIS Console windows support a popup menu activated by the right mouse button.
The popup menu depends upon the item selected in the window. In the case of the main window, the popup menu includes the following subset of commands from the menu bar:
Engine menu Reconfigure, Delete, Start, Logging, Trace, Event Trace, Status,
Shut Down
Monitor menu Sessions, Processes Summary, Processes Resident, Activity
Queues, Activities Resident, Registrations, Performance
Online Help
Online Help is available from iIS Console.
• To display the Help Topics window, choose Help > Help Topics.
• To display help for the current window, press the F1 or Help key (depending on your operating system platform).
70 iPlanet Integration Server • Process System Guide • August 2001
The iIS Console Main Window
Setting Password Protection for iIS Console
You can restrict access to iIS Console by setting password protection for your active iIS environment. A password is then required to open iIS Console, as well as any other system management tools, such as Conductor Script and the iPlanet UDS
Environment Console.
Once you set a password, other users cannot open iIS Console (or Conductor Script or the iPlanet UDS Environment Console) in your active environment without using the password.
➤
To set a password for iIS Console
1.
Choose Environment > Set Password. The Enter Password window displays.
2.
Enter a password and then enter it again in the Verification password field.
3.
Click OK to set the password.
You can also use this window to change password protection for an environment by first entering the current password in the Password field and then entering the new password. If you want to remove password protection, enter the current password in the Password field, then enter nothing for the New password and click OK.
Exiting iIS Console
To exit the iIS Console, choose Environment > Exit.
Chapter 3 The iIS Console 71
Using iIS Console Windows
Using iIS Console Windows
The iIS Console is a graphical system application developed in iPlanet UDS whose windows behave in accordance with your host window system. If you use graphical applications in your host window system, the Console will be familiar.
Using the Mouse
The iIS Console behaves like any standard application in your window system—mouse clicks select objects, double-clicks open objects, and click-and-drag operations move or copy objects. If your mouse has more than one button, you use the left-most button for these operations (or, if your mouse is configured specifically for left-handed use, the right-most button).
The iIS Console also uses the right-most button to present popup menu commands as an alternative to using the menu bar. The popup menu choices presented by right-clicking depend on which, if any, items are selected in the active window.
Window Refresh Behavior
Many iIS Console windows display lists that are maintained by the engine and are in a constant state of change. iIS Console lets you determine if and how often window displays are refreshed to correspond to information maintained by the engine. Each display window has a default automatic refresh time interval setting.
You can turn automatic refresh off or on, set the automatic refresh interval, or force an immediate refresh.
➤
To turn automatic refresh off or on
1.
Enable the Automatic Refresh toggle in the bottom right of the window.
72 iPlanet Integration Server • Process System Guide • August 2001
Using iIS Console Windows
➤
To set the automatic refresh interval
1.
Choose View > Set Refresh Interval. The Refresh Interval window displays with the default time interval setting:
2.
3.
Enter a new time interval in milliseconds.
A time interval of zero turns off automatic refresh.
Click OK.
➤
To force an immediate refresh
1.
Choose View > Refresh Now.
Filtering iIS Console Lists
Many iIS Console windows provide lists you can filter using commands available on the View menu and in the right mouse button popup menu. This section describes techniques used to perform these filtering operations.
For example, suppose you select an engine and then choose Monitor > Sessions to display a list of sessions for that engine. You can filter the list displayed or find sessions that meet certain criteria using the Filter and Find commands.
Selecting Filter from the View menu or the mouse menu displays a window in which you can write an expression for filtering the session list. The expression must be of the form:
Column_name <operator> value
Chapter 3 The iIS Console 73
Using iIS Console Windows
Operators
You can build filter expressions that use both comparison and logical operators.
The comparison operators are listed in the following table:
Comparison Operator
=
<>
<
>
<=
>=
Description equal to not equal to less than greater than less than or equal to greater than or equal to
You can use a number of logical operators to join several filter expressions. The logical operators are listed in the following table:
Logical Operator and or not
Description logical and logical or logical not
Specifying Values
In a filter expression you specify the value of an object’s state or status. These are expressed as case-sensitive string values and should be enclosed in double quotes:
Object
Session
Session
Activity
State/Status Value
Active
Suspended
PENDING
74 iPlanet Integration Server • Process System Guide • August 2001
Using iIS Console Windows
Object
Activity
Activity
Activity
Activity
Timer
Timer
State/Status Value
READY
ACTIVE
COMPLETED
ABORTED
ON
OFF
Example Filter Expression
In the session list example, suppose you enter the following expression in the Filter window:
Chapter 3 The iIS Console 75
Using iIS Console Windows
The resulting session list would then be the following:
NOTE Choose Clear to revert to the default list.
Sorting iIS Console Lists
The iIS Console lets you sort sessions, activities, and process instances by name, version, primary attribute value, primary attribute name, ID, or creation time.
2.
3.
1.
From the Monitor menu select the type of information you want to sort. For example, if you want to sort process instances, choose Monitor > Processes
Resident.
In the Processes Resident window that opens, choose View > Sort.
Select the item to sort by, and indicate ascending or descending order.
76 iPlanet Integration Server • Process System Guide • August 2001
Expansion box
Using iIS Console Windows
4.
5.
If you select a text field, you can also specify that case-sensitivity apply to the displayed text by checking Case Sensitive Text Comparison.
Click OK.
NOTE The items you can sort by varies according to the monitor window whose items you are sorting.
On Windows platforms, you can also specify an ascending sort by clicking a column name. For a descending sort, press Control while clicking the column name.
Using List Views
The iIS Console provides iPlanet UDS list views in the main window and the
Engine Status window so you can browse engines and engine components.
You might be familiar with list views as the file directory display mechanism in your host window system. iPlanet UDS list views behave like the File Manager application in Microsoft Windows. This program displays hierarchical information successively indented from left to right. To select an element in a list view, you click it. To open an element to get a list of sub-elements, you double-click the element, then either press Enter while it is selected or click its expansion box.
The expansion box lets you open or close the list of elements “below” the current element in the hierarchy. If the expansion box displays a + (plus), click the box to open the list. If the expansion arrow displays a – (minus), click the box to close the list.
Figure 3-2 iIS Console Browser
Chapter 3 The iIS Console 77
iIS Console Main Window Command Summary
iIS Console Main Window Command Summary
The following tables summarize the commands available from the iIS Console main window.
Environment Menu
Command
Alarms…
Registrations…
Aliases…
Set Password…
Print…
Print Setup…
Exit
Description
Lets you view all alarms received from the selected engine.
Provides submenus for registering (and unregistering) process definitions, assignment rules, user validations, and user profiles with one or more engines.
Provides submenus for registering (and unregistering) aliases with one or more engines. Aliases are used in specifying subprocess activities.
Opens a password entry window where you can set password protection for opening iIS
Console in your active environment. Once you set a password, other users cannot open the iIS
Console (or Conductor Script) in that environment without using the password.
Prints the iIS Console main window.
Displays the Page Setup window for the window system.
Closes the iIS Console and all open windows.
See…
—
—
78 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Main Window Command Summary
View Menu
Command
Refresh Now
Set Refresh Interval…
Window List…
Description
Forces an immediate refresh of the engine list in the main viewing panel.
Opens a Refresh Interval window where you can set the time interval between automatic refreshes of the window display.
Displays a list of open windows from which you can select a window to bring to the foreground.
See…
—
Engine Menu
Command
New…
Description
Opens a new engine configuration window in which you specify the component partitioning and static properties of a new engine.
Reconfigure… Opens an engine configuration window for the selected engine in which you can modify the component partitioning and startup properties as specified in the engine configuration file.
Duplicate…
Delete
Start…
Logging…
Creates a duplicate of the selected engine. A duplicated engine contains the same configuration as the original engine.
Lets you delete an engine configuration for the selected engine.
Opens an engine startup window in which you can start the selected engine or any of its components.
Opens a dynamic database reconfiguration window in which you can dynamically change which database tables are being logged (current state or history log or both) as well as change the history log volume. The changes you make in this window do no change the startup configuration.
See…
Chapter 3 The iIS Console 79
iIS Console Main Window Command Summary
Command
Trace…
Description
Opens an engine trace window in which you display messages, of the type you specify, generated by the various engine components.
Event Trace… Opens the engine event filter window which lets you select the type of filter to use for displaying engine events as well as a filter time interval.
Status… Opens an engine status window in which you can view the status of the selected engine or any of its components.
You can also change the state of engine units.
Shut Down Shuts down the selected engine and all its components.
See…
Monitor Menu
Command
Sessions…
Processes
Summary…
Processes
Resident…
Activity
Queues…
Description
Opens the engine sessions window, which displays the list of active sessions for the selected engine. You can monitor and manage sessions from this window.
Opens the processes summary window, which displays the list of all process definitions for the selected engine and the number of instances of each. You can open a named process definition to get a list of the process instances, displaying information about each.
Opens the engine process instances window, which displays the list of all process instances for the selected engine. You can sort this list by process name, primary process attribute, process_id, or creation time. You can open a listed process instance to get information about its activities, attributes, timers, and so on.
Opens the engine activity queues window, which displays the list of all activity queues for the selected engine. Activity queues are always resident in the engine. You can open a listed queue to get a list of activities in the queue, and so on.
See…
80 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Main Window Command Summary
Command
Activities
Resident…
Description
Opens the engine activity instances window, which displays the list of all activity instances for the selected engine. You can sort this list by activity name, activity
ID, activity state, and process name. You can open a listed activity instance to get information about its type, description, sessions whose activity list it is on, process attributes, timer links, and so on.
Registrations… Opens the engine registrations window, which displays the list of process definitions, assignment rules, user profiles, user validation, and aliases currently registered with the selected engine. This window can be the launch point for monitoring and managing execution of processes registered with the engine—for example, you can monitor the status of all process instances of a given named process. You can also deregister a registered item from the selected engine.
Performance… Opens the performance window, which displays histograms of four agent data types (instruments) that characterize the performance of the selected engine.
See…
Help Menu
Command
Contents
About iIS…
Description
Opens the Help Topics window that lets you navigate the iIS process management online help system.
Displays information about the iIS product.
See…
—
Chapter 3 The iIS Console 81
iIS Console Main Window Command Summary
82 iPlanet Integration Server • Process System Guide • August 2001
Chapter 4
Managing Engines
This chapter describes how to manage iIS process engines. It covers the following topics:
• configuring an engine
• starting an engine
• monitoring and changing the state of an engine
• reconfiguring an engine to accommodate increased load, improve performance, or recover from failure
• managing an engine database
Production Engines Versus
Development Engines
Engine use in production environments can differ significantly for use in development environments. In a development environment, the engine is used principally for testing and debugging purposes, while in a production environment, the engine must support mission-critical operations.
These different use requirements translate into differences in the way you are likely to configure and manage an engine. The table below summarizes some of the issues.
Production Engine
Multiple engines might be needed for organizational reasons or to handle heavy production loads.
Development Engine
A single engine is normally sufficient for testing purposes.
83
Production Engines Versus Development Engines
Production Engine
State information is needed for recovery: current state logging to the engine database is always turned on.
Backup engine unit and governor is needed for failover.
A number of database services are normally required to meet engine performance (database access) requirements.
Historical process execution information is needed to analyze and improve system performance: logging of historical state information is normally turned on.
Engine is rarely cold started: registration and history information would be lost.
Application upgrades need to be performed without interrupting process execution.
Resource limitations need to be monitored to ensure engine performance and stability: memory, disk space, and cpu utilization.
Development Engine
State information does not need to be stored in the engine database: current state logging can be turned off.
Failover is not critical: a minimal engine configuration is adequate.
A single database service is normally adequate.
Current process execution information is more important than historical information: history logging can be turned off.
Engine is often cold started: registration information is purged, allowing for a clean engine state.
Engine can be shut down and cold started to perform application upgrades.
Resource limitations rarely are of concern in development environments.
Keep these issues in mind when configuring an engine. In most situations, you have to configure and manage at least one development engine and one production engine.
NOTE Do not use the same engine for both development and production.
84 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
Configuring an Engine
An iIS process system can have any number of engines. For example, one engine might be used for testing and another used for production. In other cases, organizational considerations or heavy load conditions might require a number of production engines. While engines can communicate with one another—a process executing on one engine can be invoked from a process executing on another—each engine operates independently. One engine, for example, cannot fail over to another engine.
Each engine is composed of a number of engine components—engine units, governor, and database services (see
Chapter 1, “Introduction: iIS Process
Management” ). For each engine to function independently, its components must
each be identified with the engine and have a unique name, provided at startup time.
Each engine requires two levels of configuration:
• engine component partitioning
Specify which computer nodes in your environment will host the different engine components—engine units, governor, and database services.
• engine startup properties
Specify a number of startup properties required by the various engine components.
The two levels of configuration are considered separately, below.
Engine Component Partitioning
An engine that is fully configured for failover and load balancing includes all the
engine components shown in Figure 4-1 , described on
Chapter 4 Managing Engines 85
Configuring an Engine
Figure 4-1 Engine Configuration with both Failover and Load Balancing
Client Applications iIS Process
Engine
Governor
Primary
Engine
Unit
Router
Database
Services
Backup
Engine
Unit
Engine
Database
During installation, you decided which nodes in your iPlanet UDS environment
(engine servers) would have engine components installed on them. You must also determine your engine component partitioning: which engine components (if any) will run on each engine server.
The partitioning scheme that provides the highest failover reliability and the highest performance depends on a number of different factors. These factors include the power and reliability of your servers, the bandwidth of your network, the normal load on the iIS process engine, and how this load is distributed over a typical work day. Since these factors vary from site to site, only some very general guidelines are discussed here.
Primary Engine Unit It is recommended that you assign the primary engine unit to a fast, reliable server node. The primary engine unit in a production situation normally maintains sessions with hundreds of clients, maintains state information on tens of thousands to millions of objects, and performs all the computations required of an engine.
Backup Engine Unit It is recommended that you assign the backup engine unit to a capable server node also, but a different one from the node on which the primary engine unit runs (to provide backup should the primary server fail). This node could be a less powerful computer if you are willing to accept a possible decrease in performance for your backup unit.
86 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
Governor The governor does not do much processing and does not require a high performance server. It is recommended that you not assign it to the same server as either the primary or backup engine unit, because it would then not be able to distinguish between failure of the primary engine unit and a break in the network link between the engine units.
Database Services The number and placement of database services depends on load conditions. You must have enough database services running to prevent database access requests from backing up in the database service router (see
“Viewing Performance Indicators” on page 222 ). In general, assign high priority
database services to a very capable server node, probably the same as the one on which the database manager resides. If your database system provides network access to the database, such as ORACLE’s SQL*Net, then lower priority database services can be assigned to under-utilized servers, where resources are available to help carry heavy loads on the engine. (If your database system does not provide network access to the database, then your database services must reside on the same node as your database manager.)
A typical configuration is illustrated in Figure 4-2 on page 88 .
In this illustration the database services on Server4 are used in a round-robin fashion unless the load on the engine is too heavy for them to carry it. In that case the database service on Server1 is used. The database service on Server3 will be used to handle peak loads, but will get less work than the service on Server1.
You did not have to decide at iIS installation time exactly which engine components would be assigned to each server node because all component partitions are installed on each server node that supports an engine. Instead, you must select which components to start on which nodes when you configure each engine.
For example, you can designate a default set of database services that are started at engine startup time. Subsequently, however, you can start up additional database services on designated nodes, as needed, to accommodate increasing load on the engine.
The location of the primary and backup engine units is best determined in advance, before startup time, and should not change because the shared library files corresponding to process definitions registered with the engine are needed on all the nodes on which the engine units are located. For this reason, moving the engine units from one node to another can take a long time.
Your default engine component partitioning scheme is stored in an engine configuration file, allowing you to design your basic engine component partitioning scheme in advance and consistently start up your engine the same way every time.
Chapter 4 Managing Engines 87
Configuring an Engine
Figure 4-2 Typical Engine Partitioning Scheme
Clients
Server 1
Governor
Database
Service
Server 2
Primary Engine Unit
Router
Server 3
Backup
Engine
Unit
Database
Service
Server 4
Priority=9
Priority=8
Engine
Database
Priority=10
Database
Services
Engine Startup Properties
Before you start an engine, you must specify a number of startup properties. These properties are stored in the engine configuration file. The startup properties are the following:
88 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
Engine name An alpha-numeric name used to identify the engine in a given environment.
Environment An alpha-numeric name that specifies the iPlanet UDS environment in which the engine resides.
Database Configuration Properties Properties needed to access the engine database. These properties include:
• database type
• database name
• user name
• user password
Database Logging Settings These settings specify whether state information is logged and which history information tables are updated by the engine.
Process Engine Components A minimal engine configuration contains an engine unit component and a database service component. An engine configured for failover also contains a Governor component.
Memory Settings These settings specify the object memory heap size allocated to the various engine components (governor, database services, and engine units).
Included here is also a setting to limit the number of console monitor windows that can be open at any time.
Stack Size These settings specify the memory size of each thread started for the process engine components. Default values vary for each platform. Typically, you do not need to override the default values. For information on setting stack size in an iPlanet UDS environment, refer to the discussion on FORTE_STACK_SIZE in the iPlanet UDS System Management Guide.
Process Execution Options These settings specify how an engine manages process execution. By setting these options appropriately, you can ensure that memory resources do not become overtaxed during process execution, and thereby avoid engine performance degradation or possible failure.
Engine Recovery Options These options specify the behavior of the engine during recovery from an engine failure. They determine how long an engine waits for client sessions to reconnect, and the action to take if the client sessions do not reconnect after the timeout period expires.
Chapter 4 Managing Engines 89
Configuring an Engine
Engine Configuration File
The engine component partitioning and engine startup properties are stored in an engine configuration file in the following location on the central server node in your environment:
FORTE_ROOT/sysdata/conductr/clN/environment/engine_name.cfg
Path Element environment engine_name
Description
Name of the iPlanet UDS environment in which engine resides.
Name of the iIS engine.
A sample configuration file is reproduced below:
FILE_VERSION = 2.0
GOVERNOR = Server4
UNITS = Server1:Primero:P,Server3:Secundo:B
DBSERVICES = Server2:DBService1:10,Server4:DBService2:9,…
DATABASE_TYPE = ORACLE
DATABASE_NAME = @oracle_Server2
DATABASE_USER_NAME = wftester
DATABASE_USER_PASSWORD = *#@$!!
LOGGING= ON,STATE,LOG,LOG_ACTIVITIES,LOG_ATTRIBUTES,LOG_LOCKS,…
GOVERNOR_MEMORY_FLAG = n:2000,x:10000,…
DBSERVICE_MEMORY_FLAG = n:2000,x:10000,…
UNIT_MEMORY_FLAG = n:10000,m:30000,…
GOVERNOR_STACK_SIZE = 48000
DBSERVICE_STACK_SIZE = 96000
UNIT_STACK_SIZE = 96000
UNIT_RECOVER_CURSOR_SIZE = 123
DATABASE_PROC_SEGMENT_SIZE = 256
DATABASE_SESS_SEGMENT_SIZE = 256
UNIT_MAX-SESSION_NUMBER = 300
UNIT_MAX-PROCESS_NUMBER = 0
UNIT_IN_MEMORY_PROCESS_LIMIT = 1000
UNIT_SWAPOUT_INTERVAL = 10000
MONITOR_DISPLAY_LIMIT = 10
UNIT_SESSION_RECONNECT_LIMIT = 600000
UNIT_SESSION_RECONNECT_ACTION = 2048
UNIT_SNS_RATIO = 70
90 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
The engine properties specified in the configuration file are described in the following table:
Table 4-1 Process Engine Configuration Properties
Property Type of value
FILE_VERSION
GOVERNOR string string
UNITS string
DBSERVICES
DATABASE_TYPE
DATABASE_NAME
DATABASE_USER_NAME
DATABASE_USER_PASSWORD
LOGGING string string string string string string
Description
Internal use. Do not modify.
Specifies the node on which governor component runs.
For each engine unit, specifies the node on which the unit runs, unit name, and preferred priority (P=primary unit, B=backup unit, or
N=no preference). String contains entries, separated by commas, in the form
[NODE_NAME:UNIT_NAME:P/B/N][,…].
For each database service, specifies the node on which the service runs, service name, and priority (integer—positive or negative). String contains entries, separated by commas, in the form
[NODE_NAME:SERVICE_NAME:PRIORITY][,
…].
Database type. Can have the following values:
ORACLE, SYBASE, …(any database system supported by iPlanet UDS).
Name of database.
Database logon user name.
Database logon password. The password is encrypted.
Specifies which tables (current state and history log) are enabled and which object state changes are recorded if the history log is enabled. String contains any of the following entries, separated by commas, that are enabled:
[STATE] [,LOG] [,LOG_ACTIVITIES]
[,LOG_ATTRIBUTES] [,LOG_LOCKS]
[,LOG_PROCESSES] [,LOG_SESSIONS]
[,LOG_TIMERS]
Chapter 4 Managing Engines 91
Configuring an Engine
Table 4-1 Process Engine Configuration Properties (Continued)
Property Type of value
Description
GOVERNOR_MEMORY_FLAG string
DBSERVICE_MEMORY_FLAG
UNIT_MEMORY_FLAG
GOVERNOR_STACK_SIZE
DBSERVICE_STACK_SIZE
UNIT_STACK_SIZE
UNIT_RECOVER_CURSOR_SIZE
DATABASE_PROC_SEGMENT_SIZE
DATABASE_SESS_SEGMENT_SIZE
UNIT_MAX_SESSION_NUMBER
UNIT_MAX_PROCESS_NUMBER
UNIT_IN_MEMORY_PROCESS_LIMIT
UNIT_SWAPOUT_INTERVAL string string integer string integer integer integer integer integer integer
Specifies memory options. Uses the same syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,….
Specifies memory options. Uses the same syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,….
Specifies memory options. Uses the same syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,….
Specifies the memory size for each thread started for the process engine components.
Default values vary for each platform. For information on setting stack size in an iPlanet UDS environment, refer to the discussion on FORTE_STACK_SIZE in t he iPlanet UDS System Management Guide .
Specifies number of process instances to be recovered at one time in the event of engine unit failure.
Specifies segment size for storing text-based process attributes. Default value is 255 bytes.
Specifies segment size for storing text-based session attributes (associated with a session’s user profile). Default value is 255 bytes.
Specifies number of concurrent sessions supported by the engine. Default value is 300.
Specifies the number of concurrent process instances supported by the engine. Default value is 0 (no maximum).
Specifies the number of process instances retained in memory. Default value is 1000.
Specifies the time interval (in milliseconds) at which the engine checks the number of process instances resident in memory and swaps out dormant process instances. Default value is
10000.
92 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
Table 4-1 Process Engine Configuration Properties (Continued)
Property Type of value
Description
MONITOR_DISPLAY_LIMIT integer
UNIT_SESSION_RECONNECT_LIMIT
UNIT_SESSION_RECONNECT_ACTION
UNIT_SNS_RATIO integer integer integer
Specifies the maximum number of Cconsole monitor displays that can be simultaneously open by all Cconsole sessions monitoring the engine. This limit affects the Sessions, Processes
Resident and Activities Resident monitor windows. The number of these windows that are open affects the performance of the engine.
During engine recovery, specifies the time (in milliseconds) that an engine waits for clients to reconnect to a session. Default value is 60000 milliseconds (10 minutes).
During engine recovery, specifies the action to take (suspend or terminate) for client sessions that fail to reconnect before the specified timeout period
(UNIT_SESSION_RECONNECT_LIMIT).
Default value specifies to suspend sessions that do not reconnect.
Specifies the ratio of swapable to non-swapable processes for the process engine. Processes that are not marked as recoverable (either through the process definition or by a process client calling CreateProcess) cannot be swapped out of memory by the engine. Adjust the default value only if you are having performance problems with the process engine.
Customizing Engine Database Schema
iIS provides a default database schema that it uses to create an engine database.
This default schema can be used in a development environment without modification. However, for deployed applications, you can modify the database schema according to your own database requirements. Typically, you modify the schema to add table space qualifiers or other database-specific qualifiers to the
CreateTable and CreateIndex statements.
Chapter 4 Managing Engines 93
Configuring an Engine
When you configure a new engine, the default engine schema is specified by the following file on the central server node in your environment:
FORTE_ROOT/sysdata/conductr/clN/environment/engine_name.dbs
Path Element environment engine_name
Description
Name of the iPlanet UDS environment in which engine resides.
Name of the iIS engine.
The database schema file uses XML to define SQL statements for the schema. When you perform a cold start on an engine, iIS uses the specification in this file to create the engine database.
If you want to modify the default schema, before performing a cold start on an engine, edit this file according to your needs.
CAUTION When modifying an engine database schema, do not change any basic table definitions or index definitions, and do not change any column names or column data types. You should only modify information specific to a database or site, such as the table space qualifiers. Otherwise, the engine may not start. Examine the engine log file (at FORTE_ROOT/log) to determine the cause of startup failure.
94 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
The following example shows how to modify the create index statement for the
WFHActivity table to include a table space qualifier.
Code Example 4-1 Generated Definition (Oracle)
<FNCreateIndexStatement> create unique index wfk_act on WFHActivity ( processid, id)
</FNCreateIndexStatement>
Code Example 4-2 Modified Definition
<FNCreateIndexStatement> create unique index wfk_act on WFHActivity ( processid, id)
TABLESPACE my_ProcessEngine_Index
</FNCreateIndexStatement>
How to Configure a New Engine
The easiest way to configure a new engine is to use the iIS Console to create a new engine configuration file and place it in the proper directory location on your central server node. (You can also create a new configuration file by directly
entering the information in “Engine Configuration File” on page 90 into the file.)
Chapter 4 Managing Engines 95
Configuring an Engine
➤
To configure a new engine
1.
Choose Engine > New. The Configure New Engine window displays:
2.
3.
Enter a name for the new engine in the Engine name field.
The name can be case-sensitive and of any length, but have no spaces.
Click the Database tab to display the database properties dialog:
96 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
4.
Enter the database configuration properties.
For information on the Database Connection fields, refer to the iIS online help.
The Text Attribute Segment Size fields allows you to specify the segment length for process attributes and user profile information for a session.
Property
Process attribute segment size
User profile attribute segment size
Description
Specifies segment size for storing text-based process attributes. Default value is 255 bytes.
Specifies segment size for storing text-based session attributes (associated with a session’s user profile).
Default value is 255 bytes.
5.
Click the Logging tab to display the logging properties dialog:
Chapter 4 Managing Engines 97
Configuring an Engine
6.
Specify the engine database tables (Current state and/or History log) for which you want to log information. If you write to history log tables, specify the information to log.
Current state This setting determines whether the engine writes information about the current state of all sessions, processes, and process components to the current state tables (see
Appendix B, “Engine Database Schema” ). You
cannot recover an engine or support failover of an engine unit unless you enable the Current state option.
History log This setting determines which information, if any, the engine logs about each state change in sessions, processes, and process components to
the history log tables (see Appendix B, “Engine Database Schema” ). The
history log tables are used for obtaining historical information about process execution. The history log can grow quite large, so set logging selectively. You may have to monitor, back up, and flush the history log tables on a regular basis. For more information, see
“Managing an Engine Database” on page 124
.
NOTE The registration tables are always enabled for registering process definitions, assignment rule dictionaries, user profiles, a validation, and aliases. Therefore, no option for the registration table appears in the dialog.
98 iPlanet Integration Server • Process System Guide • August 2001
7.
Select the Components tab.
The Component Partitioning dialog is displayed.
Configuring an Engine
8.
Specify the engine component partitioning.
When assigning a component to a node, be sure that the node is an engine server node (that is, that engine components were installed on the node during iIS installation). The Node drop list shows all server nodes (whether online or not) defined in the iPlanet UDS environment.
The order in which you specify components is not important.
Governor To provide failover for an engine, you need to include a governor in the configuration. The governor does not accept a name or priority
(indicated by “N/A” in the table).
Engine Unit You can specify one or two engine units in your configuration—to provide failover, you need two units (a primary and a backup). For each engine unit, you must provide a name and indicate whether it is the primary unit (P), backup unit (B), or not specified (N). In the last case the governor decides which is primary and which is backup. For failover to work, the engine units must be put on separate nodes and cannot be on the node hosting the governor.
Database Service You can specify as many database services as you need (at least one) to balance the maximum load on your engine database access. For each database service, you must provide a unique name and indicate its priority. A priority is simply an integer (positive or negative from 1 to 10), with
Chapter 4 Managing Engines 99
Configuring an Engine
9.
a higher numeric value signifying a higher priority. It is suggested that you decide on a sensible set of priorities. A default priority of “1” is used if you do not specify a priority. The engine distributes the database access load based on
this priority. See “Full Configuration: Failover and Load Balancing Combined” on page 35 .
Database services must be placed on the node where your database manager resides, unless your database system provides network access to the database, such as ORACLE’s SQL*Net. If your database system provides network access to the database, then lower priority database services can be assigned to under-utilized servers where resources are available to help carry heavy loads on the engine. Any node that hosts a database service must be specified in the iPlanet UDS environment definition as supporting a database resource manager (otherwise, a database service will not be installed on the node).
Click the Options tab to display the Options dialog:
100 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
10.
Specify memory options for the governor, database service, and engine unit memory flags if you want to override the default values.
The settings you are most likely to change are the minimum and maximum memory allocation for engine units. The minimum allocation specifies the default size of the object memory heap and the maximum allocation sets the upper limit to which the iPlanet UDS memory manager can expand the object memory heap. The default values might prove insufficient for engines that are processing thousands of process instances, each with many activities, attributes (and locks), timers, sessions, and so forth.
To specify memory options, use the following syntax:
memory_option {: | =} number [, memory_option {: | =} number]
Do not include any spaces.
For example, n:4096, x:16384 specifies both maximum and minimum sizes of the iPlanet UDS memory heap. The n and x memory options are described in the following table (a page is 1024 bytes of memory).
Memory Option n x
Description
Minimum number of pages managed by the memory manager.
The value specifies the absolute minimum number of pages that will be allocated to the memory heap. Range is 1024 to 4194304
(32384 on WIndows 3.1). Must be less than the x memory option.
The default value is 2048.
Maximum number of pages managed by the memory manager.
The value specifies the absolute maximum number of pages that can be allocated to the memory heap. Range is 1024 to 4194304
(32384 on Windows 3.1). Must be greater than the n memory option. The default value is 16384.
For more information about the iPlanet UDS memory manager and other memory options, see the iPlanet UDS System Management Guide.
Chapter 4 Managing Engines 101
Configuring an Engine
11.
Specify how many monitor windows can be open at any time.
The Monitor Display Limit option (default value of 10), indicates how many iIS
Console monitor windows can be open at any time. This limit applies to
Sessions, Processes Resident and Activities Resident monitor windows and affects all iIS Consoles monitoring the engine. The number of monitor windows open affects the performance of an engine.
NOTE If you attempt to open additional windows beyond the limit, an error message is displayed.
12.
Specify the recover cursor size.
You can set the number of process instances to be recovered at one time in the event of engine unit failure. The default is 100 process instances at a time. The cursor size controls how many rows are accessed from the engine database.
Lowering the number of instances (by lowering the cursor size) reduces the amount of memory needed for recovery; the trade off is a slower recovery. If your resources permit, you can increase the number for maximum efficiency.
NOTE If the engine unit fails to recover due to an out-of-memory error, you can lower the cursor size. Another option is to increase the maximum memory allocation for DB services or engine units as your resources permit.
13.
Specify process execution options.
You can set a number of configuration options that affect how an engine manages process execution. By setting these options appropriately, you can ensure that memory resources do not become overtaxed during process execution, and thereby avoid engine performance degradation or possible failure.
102 iPlanet Integration Server • Process System Guide • August 2001
Configuring an Engine
The process execution options are the following:
Process Execution
Option
Maximum number of sessions
Maximum number of processes
Memory-resident process limit
Swap-out interval
Description
The maximum number of concurrent sessions supported by the engine. Attempts to open additional sessions will raise an exception. The default value is 300.
The maximum number of concurrent process instance executions supported by the engine. Attempts to instantiate additional process instances will raise an exception. The default value is 0 (no maximum)
The number of process instances retained in memory.
When the number of memory-resident process instances exceeds this limit, the engine swaps out dormant process instances, allowing for execution of newly activated process instances. The default value is 1000.
The time interval (in milliseconds) at which the engine checks the number of process instances resident in memory and swaps out dormant process instances. The default value is 10,000 milliseconds.
For information about how to use these configuration options, see
Tune Process Execution” on page 116 .
14.
Specify engine recovery behavior.
If an engine goes down, and then recovers, you can specify how long the engine waits for clients to reconnect and the behavior of the engine in the event the client does not reconnect before the timeout period.
By default, an engine waits 10 minutes (600000 milliseconds) for a client to reconnect. You can modify this value from the Options tab. If a client fails to reconnect to the engine after the timeout period, by default, the engine suspends the session. You can change the default behavior, and specify that the engine terminates the session.
15.
When you have finished configuring your engine, click the Create button to create the configuration file.
The engine configuration file is saved to a standard location on the central server (see
“Engine Configuration File” on page 90
).
Chapter 4 Managing Engines 103
Configuring an Engine
Duplicating an Engine Configuration
If you have multiple engines that need to be configured similarly, or want to add an engine with a configuration similar to an existing engine, you can duplicate an engine configuration. After creating a duplicate engine you can reconfigure the new engine to make any necessary adjustments.
You can do this from the iIS Console main window.
➤
To duplicate an engine configuration
1.
From the iIS Console main window, select the engine you want to duplicate.
2.
Choose Engine > Duplicate.
3.
Enter a new name for the duplicate engine.
The name can be case-sensitive and of any length, but have no spaces.
The duplicate engine shows up in the engine list in the iIS Console main window.
You can reconfigure the engine to make any necessary adjustments (see
Reconfigure an Engine” on page 113 ).
Deleting an Engine Configuration
You can delete an engine from the list of configured engines in your environment by deleting the corresponding engine configuration file. You can do this from the iIS Console main window.
➤ To delete an engine configuration
1.
Select an engine from the engine list in the iIS Console main window.
2.
Choose Engine > Delete.
You can also delete the configuration file manually. Its location is shown in
“Engine Configuration File” on page 90 .
104 iPlanet Integration Server • Process System Guide • August 2001
Starting an Engine
Starting an Engine
To start an engine, you start each of its components—engine units, governor, and database services. These components are applications, each consisting of a single server partition that must establish communication channels with other components.
As each of these partitions starts, it registers itself with the iPlanet UDS Name
Service and then looks in the Name Service registry for the names of other components with which it must establish a communication channel. The components can start in any order: they simply wait for the other components that they connect to. When all necessary communication channels are established, the primary engine unit can log on to its database and perform the operations that bring it online.
Each of the engine components and its start characteristics are discussed in more detail below. This background information is followed by instructions on how to start the engine using the iIS Console. For information on starting engines using
Conductor Script, see
“Starting an Engine” on page 235 .
Governor
When the governor starts, it does not try to connect to anything, but enters a state in which it is not connected to any engine units and waits for engine units to make contact. When the engine units start up, the governor determines which unit is to be primary and which is to be backup. There are three cases:
• If the first engine unit is marked as preferred primary, then the governor sets it as the primary unit.
• If the first engine unit is marked as preferred backup, then the governor sets it as the backup unit.
• If no engine unit is marked as preferred primary, then the governor sets the first to start as primary unit.
If the governor starts up after the engine units and they have independently established which is primary and which is backup, the governor accepts these settings.
Chapter 4 Managing Engines 105
Starting an Engine
The governor has four internal states, depending on its connections with the engine units:
Governor state
IDLE
E1
BOTH
E2
Description
Not connected to any engine units
Connected only to the first engine unit to start up
(EngineUnit1)
Connected to both engine units
Connected only to the second engine unit to start up
(EngineUnit2)
As the governor changes state (that is, as engine units start up and shut down), it determines which engine unit is primary based on the state of the engine units before the change occurred. For example, in going from BOTH to E2, the governor will make EngineUnit2 primary if that unit had been the backup before the state change (a normal failover scenario). In going back, from E2 to BOTH, however, it will retain EngineUnit2 as primary, even if that engine unit is marked as the preferred backup. (You can override the Governor to return EngineUnit1 to primary—see
“Changing Engine States” on page 122 .)
Engine Unit
When an engine unit starts, it attempts to connect to both the governor and its partner engine. It waits for a timeout period and exits if no connection is forthcoming. (If the engine configuration file specifies no engine unit partner, the engine unit can start up standalone, without requiring a governor or partner.)
If an engine unit starts after the governor has started, the engine unit connects to the governor. The governor determines if the engine unit is primary or backup, depending on the engine’s preferred designation or whether the engine is the first unit to start (in which case it becomes the primary unit). If the engine unit is primary, it attempts to come online. If the engine unit is backup, it enters a standby state in which it does not attempt to come online.
106 iPlanet Integration Server • Process System Guide • August 2001
Starting an Engine
If an engine unit starts before the governor, but after its partner has started, then it must negotiate with its partner to establish which unit is to become primary. If one unit has been marked as the preferred primary, then that unit becomes primary. If neither unit has been marked as the preferred primary, then the negotiation randomly determines which of the two becomes primary. If the governor starts up in the middle of this negotiation, the governor takes over and decides the issue. If the governor starts up after the negotiation is complete, the governor accepts the negotiated decision.
When an engine unit starts, it goes through an internal, transitional state
(EMBRYONIC), then assumes one of two persistent states, ONLINE or STANDBY, depending on whether it is designated as the primary or backup engine unit. The
STANDBY state is assumed immediately upon startup; however, the ONLINE state is achieved only after the engine unit has passed through a number of startup phases, such as logging on to the engine database and performing registrations with the Name Service. The startup phases are described in more detail below.
As a system manager you can override the state of an engine unit after it has started. For example, you can set the primary engine to a STANDBY state, and then set its partner to an ONLINE state, making the partner the new primary engine unit. The engine unit states are described below.
Engine unit state
EMBRYONIC
ONLINE
STANDBY
Description
Internal, transitional startup state.
Normal state of the primary engine unit. It is running, connected to the engine database, and can accept client sessions.
Normal state of the backup engine unit. It is running, but is not connected to the engine database and cannot accept client sessions.
Chapter 4 Managing Engines 107
Starting an Engine
Primary Engine Unit Startup Phases
The primary engine unit must perform a number of startup operations to come fully online. These operations depend on whether the primary engine unit is recovering from failure, is restarting an engine on an existing database, or is starting up for the first time (cold start). The primary engine unit startup phases are documented in the following table to assist you in diagnosing problems in engine startup (the phases are listed in sequential order):
Startup Phase
REMOVE_PRIMARY
CREATE_ENGINE
ATTACH_HISTORY_MANAGER
INIT_HISTORY_DB
HISTORY_INITIALIZED
COLD_DELETE
COLD_CREATE
RECOVER_OBJECTS
REGISTER_PRIMARY
INFORM_GOVERNOR
Description
Removes any existing “primary” registration in the Name Service.
This phase not included in a cold start.
Instantiates an engine object.
Beginning of the database logon phase.
Database logon phase, in which a router is created and registered with the Name Service, a communication channel with a database service is opened, and a database service logon to the database is successfully completed.
Completion of the database logon phase.
For a cold start, deletes any existing database tables.
For a cold start, creates the required database schema (tables).
Recovers all current state objects from the database and places them in engine state memory. This phase not included in a cold start.
Places a “primary” registration in the Name Service. This allows all other objects to locate the primary engine unit.
Communicates to governor that state has changed to online.
Phase #
51
52
53
54
55
56
57
61
62
63
108 iPlanet Integration Server • Process System Guide • August 2001
Startup Phase
INFORM_PARTNER
STARTUP_COMPLETE
Starting an Engine
Description
Communicates to partner that state has changed to online.
Completion of startup operations.
Engine unit now online.
Phase #
64
65
Database Service
When a database service starts, it attempts to connect to the primary engine unit. If the primary engine unit is not online, the database service continues waiting for it indefinitely.
When the primary engine unit starts up, the database service opens a communication channel to the engine’s database service router object and becomes available for use. The database service first asks the router for the name of the database along with the username and password to use for logging on (provided to the engine unit in the engine unit configuration file). It then logs on to the given database using the username and password provided.
When you start a database service, you specify a component name and a priority for it. A priority is simply an integer (positive or negative), with a higher numeric value signifying a higher priority. It is suggested that you decide on a sensible set of priorities. A default priority of “1” is used if you do not specify a priority.
When a database service starts, it may (or may not) establish a communication channel with a router, and it may (or may not) log on to the engine database successfully. The database service, therefore, can assume the states shown in the following table. If a database service detects a failure in the communication channel to the primary engine unit, it logs off the database and reconnects to a new primary unit when its router comes online.
Database service state
RouterChannel=OPEN/CLOSED
DatabaseState=TRUE/FALSE
Description
Communication channel with the database service router is open or closed.
Database logon is successful or unsuccessful.
New database services can be started at any time, and they automatically become available to the primary engine unit when they connect.
Chapter 4 Managing Engines 109
Starting an Engine
How to Start an Engine
You can start engine components from a centralized location using the iIS Console
(see
Chapter 3, “The iIS Console” ). The iIS Console uses iPlanet UDS system
management agents to start the partitions corresponding to each of the engine components, as specified in the engine configuration file.
➤
To start an engine
1.
Select an engine in the iIS Console main window.
2.
Choose Engine > Start. The Start Engine window displays:
110 iPlanet Integration Server • Process System Guide • August 2001
Starting an Engine
3.
Select a startup option.
A number of options are available for creating new engine database tables when starting an engine (see
“Managing an Engine Database” on page 124 ):
Startup Option warm cold newLog newState newState newLog newState newRegistration
Description
No new database tables are created during the primary engine unit startup process. All information stored in the existing database will be recovered. This option cannot be used the first time an engine is started.
Note: If you need to maintain data between iIS releases, or dump and restore data for other reasons, you can use the
Dump/Restore utility. For details, see “Dumping and Restoring
.
All new database tables (current state, registration, and history log) are created during the primary engine unit startup process.
The cold option should always be used the first time an engine is started. If used in subsequent engine starts, however, the cold option will cause deletion of the existing engine database before creation of a new one—all current state information, registration, and history log data will be lost.
New history log database tables are created during the primary engine unit startup process. All history log information stored in an existing database will be lost.
New current state database tables are created during the primary engine unit startup process. All current state information stored in an existing database will be lost.
New current state and history log database tables are created during the primary engine unit startup process. All current state and history log information stored in an existing database will be lost.
New current state and registration database tables are created during the primary engine unit startup process. All current state and registration information stored in an existing database will be lost.
CAUTION Be careful when specifying startup options. All options other than “warm” can result in loss of data. You are asked to confirm a cold start.
Chapter 4 Managing Engines 111
Starting an Engine
4.
5.
Disable the engine components you do not want to start.
By default, all components specified in your configuration file are enabled.
Click Start.
The governor, engine units, and database services are started, in that order.
NOTE The engine might take some time to start. To check the status of the engine, use the Engine > Status command as explained in
“Monitoring Engines and Engine Components” on page 118
. For a quick indication of status, check the status indicator in the Start
Engine window (see indicator states in “Main Viewing Panel” on page 69 ).
If the primary engine unit remains offline, then the engine has not started successfully. A typical reason for startup failure is that the database service has failed to open a session with the engine database.
Ultimately, you may have to check engine component log files. The log file for each component is written in the FORTE_ROOT/log directory of the node on which the component is executing. This is not necessarily the node on which you are running iIS Console.
Once an engine component has come online, you can access the log file directly from within iIS Console, as described in
“Engine Log Files” on page 210
.
➤ To start individual engine components
1.
In the iIS Console main window, select the engine whose components you want to start.
2.
Choose Engine > Start. The Start Engine window displays (see previous page).
3.
4.
Deselect the engine components you do not want to start.
Examine the state icon of any component you want to start to ensure it is not already online.
Click Start.
If an engine component is already running, you get an error message.
112 iPlanet Integration Server • Process System Guide • August 2001
Reconfiguring an Engine
Reconfiguring an Engine
An engine’s component partitioning and startup properties are stored in its engine configuration file, which is read at engine startup time. To reconfigure an engine you modify the configuration file and restart the engine. Some limited reconfiguration, such as modifying the logging of historical state information, can
be performed dynamically: you do not have to restart the engine (see “How to
Dynamically Modify Database Logging” on page 115 ).
Most reconfiguration involves modifying engine component partitioning to accommodate changing load on an engine or component failure. For example, if the load on your engine increases, you might have to start up additional database services, or if a primary engine unit fails (say, the server blows up), you might have to start up an additional engine unit to serve as backup to the failover primary.
In these cases, you must modify your engine configuration file, in the first case to include additional database services, and in the second case to put an engine unit on a different server node.
How to Reconfigure an Engine
You can statically reconfigure an engine whether or not it is currently ONLINE, either by editing the engine configuration file manually or by using the iIS Console as follows:
➤
To reconfigure an engine
1.
Select an engine in the iIS Console main window.
Chapter 4 Managing Engines 113
Reconfiguring an Engine
2.
Choose Engine > Reconfigure. The Reconfigure Engine window displays:
3.
4.
5.
Select the appropriate tab to modify the property or properties you want to change.
When you have finished reconfiguring your engine, click Save.
The modified information is written to the engine configuration file.
Restart your engine for reconfiguration changes to take effect.
114 iPlanet Integration Server • Process System Guide • August 2001
Reconfiguring an Engine
How to Dynamically Modify Database Logging
To change the logging configuration of your engine, normally to reduce or increase the amount of historical state information being logged to your engine database, you do not have to restart the engine.
➤
To modify database logging for an engine
1.
Select an engine in the iIS Console main window.
2.
Choose Engine > Logging. The Logging window displays:
3.
4.
Enable (or disable) the database tables to enable (or disable) logging.
Click Apply.
The changes you make are implemented immediately; however, they are not written to your engine configuration file. To make changes that will be saved to
the engine configuration file, see “How to Reconfigure an Engine” on page 113 .
Chapter 4 Managing Engines 115
Reconfiguring an Engine
How to Tune Process Execution
The performance of an engine depends on available system resources, such as memory. For example, if engine memory resources become overtaxed, engine performance can degrade, and an engine can even fail.
It is hard to know in advance the memory resources required under production loads. Memory requirements depend upon the number of sessions being supported and the number and complexity of concurrently executing process instances—the number of activities, timers, process attributes, and so forth. Hence, to prevent failure, it is necessary to monitor the performance of the engine under production loads, and to reconfigure it when performance begins to degrade.
A number of configuration options are available for tuning process execution, as described in
• Maximum Number of Sessions
• Maximum Number of Processes
• Memory-resident Process Limit
• Swap-out Interval
For example, you can use the first two options to limit the number of concurrent sessions or process instances that the engine supports. While this can keep process execution within resource limits, it also limits the load that an engine can support.
A more sophisticated approach is to use the engine’s advanced process management capabilities. These capabilities allow the engine to swap out dormant process instances in order to reuse the memory space they occupy. When these process instances are subsequently needed, they are swapped back into memory, replacing other process instances that are not currently being used.
In other words, only the most recently needed process instances are kept resident in memory. By swapping process instances out of and back into memory, the engine can support process execution loads that would otherwise exceed available memory resources and cause the engine to fail. Of course, there is overhead involved in this kind of process execution management, so in some cases, performance can be impacted.
The engine’s mechanism for managing process execution depends on the values of two engine configuration options: the Memory-resident Process Limit and the
Swap-out Interval. As process execution proceeds, the engine checks that the number of process instances resident in memory does not exceed the
Memory-resident Process Limit. If it does, the engine swaps out the least recently
116 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Changing Engine States used process instances (and all their associated activities, timers, and process attributes), until it brings the number of memory-resident process instances back within the limit. The engine performs these checks periodically, as specified by the value of the Swap-out Interval.
When a swapped-out process instance is subsequently needed, for example, to change the state of an activity, to handle an expired timer, to evaluate an assignment role, and so forth, the engine finds the process instance in the engine database’s current state tables and swaps it back into memory.
In general, you want the value of the Swap-out Interval to be short enough so that, under heavy load conditions, the number of process instances in memory cannot grow to a point where the available memory resources are exceeded. However, if you make the interval too short, the engine is incurring excessive overhead, swapping more process instances out of and into memory than is needed.
Similarly, the value of the Memory-resident Process Limit must be set in accordance with the memory required by executing process instances (which depends on their complexity), the available memory resources, and the value of the
Swap-out Interval.
Despite the difficulty of determining the optimum values of each of these configuration options, the combination provides great flexibility in tuning an engine to process the heaviest loads, with the greatest performance, and with the least risk of failure.
NOTE The evaluation of role-based assignment rules—as compared to assignment rules that involve process attributes or linked activities—does not require that the corresponding process instance be resident in memory. Hence, much less swapping is generally involved in executing process instances that employ only role-based assignment rules.
Monitoring and Changing Engine States
After you have started an engine, you should verify that it has started successfully and monitor it periodically. In some situations, you may want to dynamically change the state of engine components.
This section starts by describing how to monitor engines and engine components with the iIS Console, followed by details on how to change engine states. For information on how to perform these operations using Conductor Script, see
“Managing iIS Process Engines with Conductor Script” on page 235 .
Chapter 4 Managing Engines 117
Monitoring and Changing Engine States
Monitoring Engines and Engine Components
You can get status information about the engine as a whole as well as about each of
the individual engine component in the iIS Console (see Chapter 3, “The iIS
Console” ). iIS Console uses iPlanet UDS system management agents to gather data
from engine components. Each agent has a set of instruments that report relevant information.
Monitoring the Engine
Typically, you want to know which engine components are running.
➤
To check the engine runtime configuration
1.
Select a running engine in the iIS Console main window.
2.
Choose Engine > Status. The Engine Status window displays:
118 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Changing Engine States
The window provides information about the runtime state of the engine and engine component partitions. Partitions that are running (even if not fully functional) are shown with a warm-up state icon. For more detail on the functional state of a component, you can select that component (governor, unit, or DBservice) in the list view on the left, and the appropriate status display will appear on the right.
NOTE The Broadcast button lets you send a message to all open sessions.
The message can be picked up by client applications or application
Monitoring Engine Components
You can get status information about individual engine components in the Engine
Status window. Selecting an engine component in this window provides more information about the functional status of a component than is displayed in the
Engine Status window if only the engine has been selected.
➤ To monitor individual engine components
1.
Choose Engine > Status to display the Engine Status window.
2.
In the list view on the left-hand side of the window, select the component to monitor: governor, engine unit, or database service.
Chapter 4 Managing Engines 119
Monitoring and Changing Engine States
The right side of the window provides information about the status of the engine component. For example, status information contained on a primary engine unit is shown below.
Engine unit In the case of an engine unit the following information is provided:
Property Description governor channel state whether the communication channel to the governor is open or closed partner channel state whether the communication channel to the partner engine unit is open or closed engine unit state whether the engine is in ONLINE or STANDBY state or offline engine unit startup phase start time node active memory allocated memory the startup phase of a primary engine unit (see
Unit Startup Phases” on page 108
) the node on which this engine unit is running
the time at which the engine unit partition started the size of the object memory heap currently used by the engine unit partition the amount of active memory currently allocated to objects created by the engine unit partition
120 iPlanet Integration Server • Process System Guide • August 2001
Property peak allocated memory
Monitoring and Changing Engine States
Description the amount of allocated memory remaining after the most recent memory reclamation (probably the best measure of active memory utilization)
Governor In the case of a governor the following information is provided:
Property governor state start time node active memory allocated memory peak allocated memory
Description the status of the governor’s connections with engine units (IDLE,
E1, BOTH, E2) as described in
the time at which the governor partition started up the node on which this governor is running the size of the object memory heap currently used by the engine unit partition the amount of active memory currently allocated to objects created by the engine unit partition the amount of allocated memory remaining after the most recent memory reclamation (probably the best measure of active memory utilization)
Database service In the case of a database service the following information is provided:
Property Description router channel state whether the communication channel to the engine unit router is open or closed database state whether the database service is connected to the database or not transactions processed start time node active memory the number of completed database transactions since the start time of the database service the time at which the database service partition started up the node on which this database service is running the size of the object memory heap currently used by the engine unit partition
Chapter 4 Managing Engines 121
Monitoring and Changing Engine States
Property allocated memory peak allocated memory
Description the amount of active memory currently allocated to objects created by the engine unit partition the amount of allocated memory remaining after the most recent memory reclamation (probably the best measure of active memory utilization)
Changing Engine States
You can change the state of an engine, which usually involves changing the state of one or both engine units or shutting down one or more engine components. You can use the iIS Console to perform many of these tasks (see
Console” ). The iIS Console uses iPlanet UDS system management agents to control
engine components.
Changing Engine Unit States
You might want to change the state of an engine unit for a number of reasons. For example, you might want to suspend all client sessions with a primary engine unit
(change its state from ONLINE to STANDBY) so you can perform administrative functions on the engine database. Or you might want to place a primary engine unit in STANDBY state so you can make its partner primary. When an engine goes back to ONLINE from STANDBY, it recovers state information from the database.
➤
To change the state of an engine unit
1.
Select a running engine in the iIS Console main window.
2.
Choose Engine > Status. The Engine Status window displays.
3.
4.
5.
6.
In the list view, select the engine unit whose state you want to change.
Click the Set State button to display the Set Engine Unit State window.
Click the radio button corresponding to the new engine unit state: ONLINE or
STANDBY.
Click the Set button.
➤
To put the primary engine unit on STANDBY and the backup unit ONLINE
1.
Select the running engine in the iIS Console main window.
2.
Choose Engine > Status. The Engine Status window displays.
122 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Changing Engine States
3.
Click the Set Primary button in the Engine Status window. The primary unit now becomes the backup unit, and the backup becomes the online unit.
About Recovering State Information
In a production system, placing a backup unit online requires recovering state information from the engine database. State information includes the state of every process instance, the state of every activity and timer within each process instance, the values of process attributes and their lock states, the state of routers and triggers for each activity instance, session activity lists, queue lists, and so on.
Accordingly, recovery of state information is not instantaneous. It takes an amount of time proportional to the amount of state information in the engine database, and inversely proportional to the speed of database access. The amount of state information available for a given process instance is determined by the process
recovery level specified in the process definition or by the client application.
The recovery level is really a performance parameter that specifies how much state information about a process instance is stored persistently in the engine database.
The less state information stored in the database, the higher the level of engine performance in executing that process instance, but the lower the level of recovery possible when a backup engine unit comes on line.
Recovery levels are specified on a per process basis (not per engine). There are three options.
None No state information is written to the engine database so none can be recovered—the process instance is therefore terminated when an engine fails and a backup unit comes on line.
Process only Minimal information is written to the engine database—only enough to recreate the process instance from its start. When an engine fails and a backup unit comes on line, all state information is lost and the process instance is recreated from start and executed anew.
Full recovery All state information for a process instance is written to the engine database. When an engine fails and a backup unit comes on line, state information is recovered as needed to proceed with process execution, that is, to evaluate assignment rules, change an activity state, and so on.
NOTE Writing of data to the engine database also depends on the logging properties of the engine configuration (see
Chapter 4 Managing Engines 123
Managing an Engine Database
For more details on recovery levels, see the iIS Process Development Guide and the
iIS Process Client Programming Guide.
Shutting Down Engine Components
You can shut down an individual component by clicking the Shutdown button in the component status display of the Engine Status window, or you can shut down all running engine components by clicking the Shutdown command in the engine status display.
Managing an Engine Database
The iIS engine database consists of three categories of tables:
Current State These tables maintain state information about all objects created in process execution so that the engine state can be recovered in case of engine failure.
The tables contain current state information on all sessions, process instances, activities, process attributes, timers, and so on.
Registration These tables maintain state information about all library distributions and aliases (see
) registered with the engine. This information can be recovered in case of engine failure.
History Log These tables maintain historical information about the most important objects created in process execution (sessions, process instances, activities, timers, attributes, and attribute locks). This information can be used in managing process execution, analyzing historical trends, and reporting on business throughput. The log also includes information about engine startup, alarms, and registration that can be used for troubleshooting purposes.
Database Management Issues
There are a number of management issues to consider regarding your iIS engine database. These issues include growth of the database, failure of the database, and recovering your data. Each is discussed below.
124 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
Growth of the Database
As with any of the enterprise databases used by your workflow application, the engine database can grow in size. The current state tables grow and shrink in proportion to the number of sessions, process instances, activities, process attributes, and timers that exist at any one time. The registration tables are typically quite small, but grow in proportion to the number of distributions or aliases you register with the engine.
The history log, however, because it accumulates historical data, can grow quite large as time goes on, eventually reaching your database storage limit. You must therefore establish a set of procedures for monitoring and limiting the growth of the history log. The following suggestions might prove useful:
• Log only the minimum historical data that you will need for process execution analysis.
See “How to Dynamically Modify Database Logging” on page 115 for history
logging options.
• Maintain an archive history log database.
When rows in your history log tables are sufficiently aged, you can delete them from the engine database and transfer them to an archive database. For example, if your system does not make use of long-running process instances, you might want to periodically transfer all rows in your history log that correspond to process instances that terminated more than two months ago.
Failure of the Database
For any number of reasons, the engine database might fail. If the engine cannot access the database (that is, it cannot write to the database), then it raises an exception and transitions to STANDBY state in which it stops process execution.
Engine exceptions are written to the primary engine unit’s log file and to the iIS
Console Alarms window. See
Chapter 7, “Troubleshooting,” for more information
on exceptions.
Recovering Data
When starting an engine, you can choose to recover or lose any existing current state, registration, or history log database tables, as long as you are not starting the engine for the first time. The various startup options are described in
“How to Start an Engine” on page 110
. When you recover the current state tables you also recover the registration tables.
Chapter 4 Managing Engines 125
Managing an Engine Database
Dumping and Restoring Data
The iIS Dump/Restore facility makes it possible to dump the data in an engine database to an ASCII file, and then, subsequently, to restore the data to the existing database or to a new engine database. It is used primarily to accommodate changes in database schema from one release of iIS to the next sequential release. However, you can also use it to back up a database, troubleshoot problems, or move data from one database system to another.
To dump or restore data for a particular engine database, the following conditions must be met:
• The iPlanet UDS Environment Manager must be running.
• The engine and database must have been configured, that is, the engine configuration file must exist.
• The engine must be shut down.
The Dump/Restore facility has two interfaces: a graphical user interface application and a command line utility. Both require information that you provide
directly or by setting a number of environment variables—see “Dump/Restore
Environment Variables” on page 136 .)
Dumping Database Tables
The following sections describe how to write the data in an engine database to an
ASCII file. You can use either the Dump/Restore application or its command-line equivalent.
126 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
Using the Dump/Restore Application
The following procedure shows how to use the Dump/Restore application.
➤
To use the Dump/Restore application to dump database tables
1.
Start the Dump/Restore application.
❍
❍ on Windows or Windows NT: double-click the Dump/Restore icon.
on UNIX, OpenVMS, or Windows NT: enter the following: ftexec -fnict -fcons
-fi bt:\$FORTE_ROOT\userapp\wfdrdump\c20\wfdrdu0
The iIS Dump/Restore window appears.
Chapter 4 Managing Engines 127
Managing an Engine Database
2.
Configure a data file in which to dump the data.
a.
Click the Configure Files tab.
b.
c.
d.
In the Directory name field, specify the directory into which the data file will be written.
The directory must already exist; the Dump/Restore application will not create a new directory.
In the Data file name field, enter the name of the data file.
Click the Set Configuration button.
128 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
3.
Specify the engine database from which to dump the data.
a.
Click the Configure Database tab.
b.
c.
In the Engine name field, enter the name of the engine whose data you want to dump.
When you exit the field, the Database type, Database name, User name, and User password fields will automatically be filled in from the engine configuration file.
Click the Open Connection button.
The status bar at the bottom of the window displays a “Database
Connected” message.
Chapter 4 Managing Engines 129
Managing an Engine Database
4.
Dump the data.
a.
Click the Dump Tables tab.
b.
c.
d.
Select the category of tables you want to dump.
By default, all categories are selected. Disable any category you do not want to dump.
Click the Dump Tables button.
Click OK in the Information dialog that is displayed.
While the dump is in progress, the status bar at the bottom of the window displays a “Dumping Tables” message. When the dump is complete, the status bar displays a “Completed Dumping Tables” message.
Using the Dump Command-line Utility
The Dump/Restore facility’s
DrDump
command writes data in the engine database into an ASCII file.
Syntax for drdump command: drdump -e engine_name [-d directory_name] [-v data_file_name]
[-t registration|state|history]
130 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
As in all iPlanet UDS command line specifications, if you use a name that includes a space, you should enclose the name in double quotation marks.
The following table describes the command line flags for the DrDump command:
Flag
-e engine_name
-d directory_name
-v data_file_name
-t registration|state| history
Description
The name of the iIS engine in the current environment. This flag is required.
The directory in which to place the data files. The default value is the root directory.
The name of the data file. The default value is dumprest.log.
The category of tables to dump. Valid values are
REGISTRATION, STATE, HISTORY. The default is all categories. To specify a combination of two categories, use a colon (:) between categories. For example:
-t registration:state
Alternatively, you can enter the -t flag for each category. For example:
-e myEngine -t registration -t state
If you have set the environment variables described in “Dump/Restore
Environment Variables” on page 136
, then you do not need to supply values for the command line flags.
Restoring Database Tables
The following sections describe how to retrieve data which has been written to an
ASCII file and restore it to an engine database. To restore data to an engine database, the engine must have been cold started. Cold starting an engine creates empty database tables that correspond to the engine database schema.
You can use either the Dump/Restore application or its command-line equivalent.
NOTE If you are upgrading to a new release and have customized your process engine database schema, be sure to read the following section,
“Preserving Engine Database Schema Customizations.”
Chapter 4 Managing Engines 131
Managing an Engine Database
Preserving Engine Database Schema Customizations
If you are upgrading to a new release of iIS, the database schema for the process engine may have changed. If, in the previous release, you modified a process engine database schema to conform to your own specific requirements, as explained in
“Customizing Engine Database Schema” on page 93 , then you must
perform the following procedure to preserve your modifications before restoring the database tables.
NOTE If you are not upgrading to a new release, or if the database schema did not change during the upgrade, then the following procedure is not necessary.
➤
To preserve custom engine database schema changes when upgrading iIS
1.
Rename your current engine.dbs
file as follows: a.
Navigate to
FORTE_ROOT/sysdata/conductr/cln/envname/engine.dbs
2.
3.
4.
5.
b.
envname is the name of your environment
engine is the name of your process engine
Rename
engine.dbs
to
engine.old
.
Start CConsole and reconfigure the process engine as follows: a.
In CConsole, select the process engine b.
Select Reconfigure, and then click Save
Compare the newly generated
engine.dbs
with engine.old
of this procedure and make the following modifications:
Modify engine.dbs
, based on the modifications from engine .
.old
.
Cold start the iIS process engine you are upgrading.
Cold starting an engine creates empty database tables corresponding to the engine database schema.
Shut down the engine.
132 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
Using the Dump/Restore Application
The following procedure shows how to restore database tables that were previously written to an ASCII file, as explained in
“Dumping Database Tables” on page 126 .
➤
To use the Dump/Restore application to restore database tables
1.
Start the Dump/Restore application.
2.
3.
Follow the instructions under
“Dumping Database Tables” on page 126 .
Configure a data file from which to retrieve the data.
a.
b.
Click on the Configure Files tab.
In the Directory Name field, specify the directory in which the data file is to be found.
c.
d.
In the Data File Name field, enter the name of the data file.
Click the Set Configuration button.
Specify the engine database in which to restore the data: a.
Click the Configure Database tab.
b.
c.
In the Engine name field, enter the name of the iIS engine whose data you want to restore.
When you leave the field, the Database type, Database name, User name, and User password fields will automatically be filled in from the engine configuration file.
Click the Open Connection button.
The status bar at the bottom of the window will display a “Database
Connected” message.
Chapter 4 Managing Engines 133
Managing an Engine Database
4.
Restore the data.
a.
Click the Restore Tables tab.
b.
c.
d.
Select the categories of tables you want to restore. By default, all categories are selected. Disable any category you do not want to restore.
Click the Restore Tables button.
Click OK in the Information dialog that is displayed.
When tables have been successfully restored, the status bar displays the
“Completed Restoring Tables” message.
134 iPlanet Integration Server • Process System Guide • August 2001
Managing an Engine Database
Using the Restore Command-line Utility
The Dump/Restore facility’s DrRestore command retrieves data which has been dumped to an ASCII file and restores it into an engine database.
Syntax for drrest
command: drrest -e engine_name [-d directory_name] [-v data_file_name]
[-t registration|state|history]
As in all iPlanet UDS command line specifications, if you use a name that includes a space, you should enclose the name in double quotation marks.
The following table describes the command line flags for the
DrRestore
command:
Flag
-e engine_name
-d directory_name
-v data_file_name
-t registration|state| history
Description
The name of the iIS engine in the current environment. This flag is required.
The directory in which to place the dump files. The default value is the root directory.
The name of the data file. The default value is dumprest.log.
The category of tables to dump. Valid values are
REGISTRATION, STATE, HISTORY. The default is all categories. To specify a combination of two categories, use a colon (:) between categories. For example:
-t registration:state
Alternatively, you can enter the -t flag for each category. For example:
-e myEngine -t registration -t state
If you have set the environment variables described in “Dump/Restore
Environment Variables” on page 136
, then you do not need to supply values for the command line flags.
Chapter 4 Managing Engines 135
Managing an Engine Database
Dump/Restore Environment Variables
iIS provides a set of environment variables for use with the Dump/Restore facility.
You can set these variables to provide values for both the Dump/Restore application and the command-line utility.
Variable
WFDR_ENGINE
WFDR_DIRECTORY
WFDR_DATAFILE
WFDR_TABLETYPES
Description
The name of the iIS engine.
The directory in which to place the dump files. The default value is the directory in which the application resides.
The default name for the data file. The default value is dumprest.log
The category of tables stored in the database. Valid values are REGISTRATION, STATE, HISTORY. To specify more than one category of tables, separate the categories with a colon. For example: WFDR_TABLETYPE=registration:state
136 iPlanet Integration Server • Process System Guide • August 2001
Chapter 5
Managing Registrations
Registration is the procedure by which programmatic information about processes, users, and so on, created in the process development workshops, is made available to a running iIS process engine, so it can be dynamically loaded and used in process execution. The programmatic information usually consists of programs
(shared libraries) created in the iIS process development workshops, but can also be logical references to executing processes, called aliases.
This chapter describes how to manage iIS process engine registrations. It covers the following topics:
• overview of registration concepts
• how to register iIS library distributions
• how to register an alias
• how to perform application upgrades
About Registration
The iIS process engine’s principal function is to execute process definitions created in the iIS process development workshops. A process definition is a program that specifies how the engine coordinates the various client applications and resources that perform the work needed to complete a business process.
Most businesses are not static, but rather are dynamic: they want to create new business processes or modify existing ones. The organizational structure might also change, impacting how work gets assigned. To provide the flexibility businesses require, the engine can dynamically load and execute new and revised process definitions, assignment rules, and other programmatic information.
137
About Registration
Registration is the procedure by which process logic created in the iIS process
development workshops is made available to a running engine (see “What Does
The entities that get registered with an iIS engine (described in detail in the iIS
Process Development Guide) include the following.
user profiles Defined in the User Profile Workshop, a user profile is logic that specifies a user information template. The engine uses this template to build individual user profiles for each engine session. These user profiles are evaluated by assignment rules in determining which users can perform activities.
validations Defined in the Validation Workshop, a validation contains a
ValidateUser method that the engine uses to validate a user (say, against an organization database) before opening a session with the engine.
assignment rule dictionaries Developed in the Assignment Rule Workshop, an assignment rule dictionary is a set of rules used by the engine to assign activities to users or other resources.
process definitions Developed in the Process Definition Workshop, a process definition is executed by the engine for each instance of the corresponding process.
The engine manages and controls the process instance from creation through termination.
aliases Used in the Process Definition Workshop to specify subprocesses, an alias is a logical reference to an executing process that provides the flexibility to execute the process on any engine.
Registration capability is provided by the iIS process development workshops.
These workshops let application system designers and process developers test their work by registering it with a test engine.
Registration capability is also provided by iIS process management tools (iIS
Console and Conductor Script). These tools let system managers register process definitions, assignment rules, user profiles, validations, and aliases with production engines in production environments.
138 iPlanet Integration Server • Process System Guide • August 2001
About Registration
What Does Registration Do?
The entity actually registered when you register a process definition, assignment rule, user profile, or user validation is a library. (Aliases are not libraries and this section does not apply to them—see
“About Aliases” on page 143 .)
A library (often referred to as a shared library) is code that can be loaded into memory at runtime, and then referenced by any number of executing programs. A library distribution is the set of distribution files used to install one or more libraries on any particular node.
In the case of iIS engine registration, library distributions are installed on the nodes hosting iIS engine units so the libraries can be dynamically loaded and executed by the engine unit or units running on the node.
iIS library distributions are generated automatically when a developer selects the
File > Distribute command in the Process Definition, Assignment Rule, User
Profile, and Validation workshops. Code in the central development repository is extracted and made into library distribution files, which are then placed in a standard location on the central server node.
NOTE You can also generate library distributions using the
MakeConductorDistribution Conductor Script command, if you have access to the central repository where development code resides. (iIS Console does not provide this capability.)
A special registration service (WFEnvAgent) running on the central server node keeps track of the iIS library distributions (process definitions, assignment rule dictionaries, user profiles, and validations) that have been made from the process development workshops or Conductor Script. Whenever an iIS library distribution is made, its compatibility level is augmented to distinguish it from any previously generated distributions.
After a library distribution has been made and it is located on the central server node, you, as a system manager, can use the iIS Console or Conductor Script to register the library with any number of engines. (iIS process developers can also register iIS library distributions for test purposes using a Register option of the File
> Distribute command in the process development workshops.)
Registration consists of two steps, illustrated in
Figure 5-1 , both transparent to the
user performing the operation.
Chapter 5 Managing Registrations 139
About Registration
Figure 5-1 Registration Steps
Central Server
Environment
Manager
Repository
Server
Central
Repository
1 Install distribution on engine nodes
Process
Development
Workshops
Engine Server
Engine Server
Primary
Engine
Unit
2
Place entry in registration table
Engine
Database
Backup
Engine
Unit
• Installing library distribution files on the nodes hosting the target engine (more specifically, hosting the target engine units).
This step is performed by iPlanet UDS system management agents. The highest compatibility level library distribution residing on the central server node is installed on the nodes hosting both the primary and backup engine units. For details of how iPlanet UDS deploys library distributions see the iPlanet UDS
System Management Guide.
• Placing an entry in the registration table of the target engine’s database.
This step is performed by iIS engine unit agents and requires that the target engine be ONLINE.
140 iPlanet Integration Server • Process System Guide • August 2001
About Registration
If at some point you have to move an engine unit to a new node, you do not have to manually re-register (reinstall) all the libraries on the new node. When an engine unit first comes on line, if the registered libraries are not currently installed on the host node, iPlanet UDS automatically installs them. This operation, however, might take some time.
Registration in Production Environments
At a production site removed from a development environment, registration can only be performed using iIS process management tools. In a production environment it is more likely that registrations will be batched, rather than performed one at a time as in a development environment. It is also more likely that library distributions will be registered with a number of engines, rather than a single test engine.
Before performing registrations in such situations, however, you have to first transfer iIS library distributions to the production environment. Use the following steps:
➤
To transfer iIS library distributions to a production environment
1.
Make sure that developers have generated all relevant iIS library distributions using either the File > Distribute command in the process development workshops or the MakeConductorDistribution Conductor Script command.
2.
Copy the iIS library distributions located on the central server node in the development environment to your distribution medium.
3.
The distributions are found in the following directory:
FORTE_ROOT/appdist/environment_ID/distribution_ID where, environment_ID is the name of the active iPlanet UDS development environment. Copy the contents of the distribution_ID directory and the required cl# directory structure beneath it. For information on the structure of library distributions, see the iPlanet UDS System Management Guide.
Transfer the iIS library distributions from your distribution medium to the central server node in the production environment.
The distributions should be placed in the
FORTE_ROOT/appdist/environment_ID/ directory, where, environment_ID is the name of the active iPlanet UDS production environment.
Chapter 5 Managing Registrations 141
About Registration
4.
Follow the instructions for registering iIS distributions in “Registering iIS
.
What Does Unregistration Do?
Unregistering process definitions, assignment rules, user profiles, or a validation does not reverse the entire registration process, just the last step of the process: it removes the registration entry from an engine’s registration database table. It does not remove the shared library files installed on the engine server node, nor does it delete the library distribution from the environment repository (where they are placed in order to be installed on engine server nodes). You can delete a library distribution from the environment repository using the Conductor Script
Uninstall command (see
).
Engine Registration Manager
Each engine has a Registration Manager that tracks library distributions registered with the engine. The manager ensures that all engine references to a library are to the most current registered version of the library.
For example, if you register a new version of a process definition with an engine, all subsequent instances of that process definition created by that engine are based on the new version. Process instances based on the older version, however, continue to execute to completion (process termination). When instances of the older version no longer exist, the engine registration manager automatically unregisters the old process definition.
When you register a new version of an assignment rule dictionary with an engine that has an older version already registered, the new versions of assignment rules are retroactively applied to all existing offered and queued activities. Offered activities are offered again to sessions based on the new rules, and access to activities in queues becomes governed by the new rules. The engine registration manager automatically unregisters the old versions of any assignment rules included in the new assignment rule dictionary.
Unregistering a library distribution removes the corresponding entry from the registration database table but does not delete the library files from the engine unit’s host server node.
142 iPlanet Integration Server • Process System Guide • August 2001
About Registration
About Aliases
An alias is a reference to a process definition registered with an engine. It is used by developers when defining a Subprocess activity in a process definition so they do not have to hard code the process name and host engine represented by the
Subprocess activity. Aliases provide the flexibility to move subprocess execution to different engines at runtime.
An alias is a logical name that is evaluated by the engine during process execution.
It references a particular process definition executed by a particular engine. An alias must be registered with every engine executing a process definition containing the alias (that is, containing a Subprocess activity referencing the alias).
For example, suppose engine1 is executing a process1 that includes a Subprocess
activity1, as shown in Figure 5-2 .
Figure 5-2 Subprocess Activity References
Engine 1
Process 1
Engine 3
Subprocess activity 1
Process 3
Engine 2
Subprocess activity 2
Process 2
The Subprocess activity1 is actually a process3 that executes on engine 3. Suppose also that engine2 is executing a process2 that includes a Subprocess activity2. The
Subprocess activity2 is also process3, which executes on engine3.
Chapter 5 Managing Registrations 143
Registering iIS Distributions
If process1 and process2 hard-code the reference to process3 on engine3, then process3 could not be moved to another engine without modifying both process1 and process2 in the Process Definition Workshop, creating the respective library distributions, and re-registering the process definitions with both engine1 and engine2. However, if process1 and process2 use an alias to reference process3 on engine3, then process3 could be moved to another engine by simply registering a new version of the alias with both engine1 and engine2.
To register an alias, specify the alias name (same as the process name) and the name of the engine executing the process definition. See
“Registering Aliases” on page 148 .
Registering iIS Distributions
Process definitions, assignment rule dictionaries, user profiles, and validations are all registered using the same procedure. Each of these types of library distributions, however, has unique registration characteristics, as described briefly below:
User Profile A user profile must be registered with every engine. The user profile is used along with the validation to authenticate users who attempt to open sessions with the engine. The user profile is also used by assignment rules in determining who has permission to perform activities. You can register more than one user profile with each engine, but this is normally done only for upgrade purposes. Each user profile registered with an engine must be uniquely named.
(An upgraded validation and upgraded assignment rule dictionary, consistent
with the upgraded user profile, must also be registered—see “Performing
Application Upgrades” on page 153 ). You cannot register an upgraded user profile
of the same name as a previously registered user profile.
Validation One, and only one, validation can be registered with an engine, which allows the engine to open sessions with client applications. Unlike process definitions, assignment rule dictionaries, and user profiles, there can be only one validation registered with an engine at any time. Subsequent registrations replace the existing validation with a new one (implicitly unregistering the old one).
Assignment Rule Dictionary If a process definition references an assignment rule, the dictionary that contains that assignment rule must be registered.
Generally, designers group assignment rules into dictionaries containing more than one assignment rule and then generate library distributions containing all the assignment rules in the dictionary. When you register an assignment rule dictionary with an engine, you have registered all the assignment rules contained in the dictionary. The engine uses only the most recently registered assignment rule, retroactively applying it to all existing activities.
144 iPlanet Integration Server • Process System Guide • August 2001
Registering iIS Distributions
Process Definition A process definition must be registered with every engine that can execute that process definition. Upgraded process definitions can be registered without unregistering the old versions: the old process definitions are used for existing process instances and the upgraded versions are used for all process instances started after the new definition is registered.
Registration Order
The distributions you register with an engine can be registered in any order with one exception: the user profile supplier of a validation or assignment rule dictionary must be registered before the validation or assignment rule dictionary is registered.
Since design elements are created before the process definitions that use them, it is normal for a user profile, validation, and assignment rule dictionary to be registered in that order, before process definitions are registered. However, in the course of development, assignment rules can change, or new ones may be developed, and these assignment rules can be registered at any time (if their user profile supplier does not change).
Performing Registrations
To register an iIS distribution, the library distribution must have been made and must reside on the central server node. The nodes hosting the target engine (or engines) must be online, and the primary engine unit of each target engine must be in ONLINE state.
As you perform registrations, iIS writes a log of registration operations. The log file is stored on the central server node in the following location:
FORTE_ROOT/sysdata/conductr/cl0/environment_name/engine_name.log
NOTE After registration of an iIS distribution has taken place, subsequent relocation of an engine unit to another node is not a problem—library distributions required by the engine unit are installed automatically (from the central server node) when the engine unit first comes on line.
You can register one or more distributions with one or more engines, all at the same time.
Chapter 5 Managing Registrations 145
Registering iIS Distributions
➤
To register one or more distributions using the iIS Console
1.
Choose Environment > Registrations> New. The Register Distributions window displays:
Distributions drop list
Distribution selection list
Engine selection list
2.
3.
4.
5.
To filter the list of distributions available for registration, select Process
Definitions, Assignment Rule Dictionaries, User Profiles, or Validation from the Distributions drop list.
In the Distribution selection list, select the distribution (or distributions) to register.
In the Engine selection list, select the engine (or engines) with which you want to register the specified distributions. All ONLINE engines are displayed.
Click OK to perform the registrations.
146 iPlanet Integration Server • Process System Guide • August 2001
Registering iIS Distributions
Upgrading Registrations
Sometimes you must register a new version (upgrade a registration) of one of these library distributions. How you upgrade a registration depends on the upgrade registration characteristics of the distribution type, as summarized in the following table:
Distribution Type
User profile
Validation
Assignment rule dictionary
Process definition
Registration Characteristics
Cannot register upgraded versions of the same name unless you first unregister the older version, cold start the engine, or rename the upgraded version.
Can register upgraded versions of the same name. Engine supports only the most recent version—automatically unregisters earlier version.
Can register upgraded versions of the same name. Engine supports only the most recent version, retroactively applying it to all existing activities.
Can register upgraded versions of the same name. Engine supports multiple versions. Engine unregisters older versions no longer being used.
Unregistering iIS Distributions
At times you might want to unregister a distribution from one or more engines, normally because those engines no longer use the process definitions they contain.
(You might also have to unregister a distribution because for some reason you want to re-register it.) Cold starting an engine unregisters all registrations; however, if you want to be more selective, use the procedure described in this section.
NOTE You cannot explicitly unregister a validation. This is because the engine maintains only one validation—registering a new validation implicitly unregisters the previous one.
You can unregister only one registered distribution at a time.
Chapter 5 Managing Registrations 147
Registering Aliases
➤
To unregister a process definition, assignment rule dictionary, or user profile
1.
Choose Environment > Registration > Unregister. The Unregister Distribution window displays:
Type drop list
Engine selection list
2.
3.
4.
In the Distribution field, enter the name of the process definition, assignment rule dictionary, or user profile to unregister.
From the Type drop list, select the distribution type.
In the Engine selection list, select the engine (or engines) from which you want to unregister the specified process definition, assignment rule dictionary, or user profile. All running engines are displayed.
NOTE You cannot unregister a validation. The validation is deleted when a new validation is registered.
5.
Click OK to perform the unregister operation.
Registering Aliases
An alias must be registered with every engine executing a process definition that references the alias. Generally, developers provide you with a list of aliases used in their process definitions, and the subprocesses these aliases specify. You then have to register these aliases with the appropriate engines, as explained below.
148 iPlanet Integration Server • Process System Guide • August 2001
Registering Aliases
Unlike process definitions, assignment rule dictionaries, user profiles, and the validation, aliases do not involve library distributions. In registering an alias, you are simply making an entry in an engine’s registration table. You can register only one alias at a time, but you can register it with more than one engine. The registration process is the same for both new and modified versions of an alias.
To register an alias, the nodes hosting the target engine (or engines) must be online, and the primary engine unit of each target engine must be in the ONLINE state.
➤
To register an alias using the iIS Console
1.
Choose Environment > Aliases > New. The Register Alias window displays:
Engine selection list
4.
5.
2.
3.
In the Alias name field, enter the name of the alias, as supplied to you by developers.
The alias name is the same as the process name of the subprocess.
In the Engine name field, enter the name of the engine the alias is referencing.
This is the name of the engine with which the specified process definition is registered and on which it will be executed. (The engine where the actual subprocess resides.)
Select the engines with which to register the specified alias.
Click OK.
Chapter 5 Managing Registrations 149
Viewing Registrations for an Engine
Unregistering Aliases
At times you might want to unregister an alias from one or more engines, normally because those engines are no longer using it. You can unregister only one alias at a time.
➤
To unregister an alias
1.
Choose Environment > Aliases > Unregister. The Unregister Alias window displays:
Engine selection list
3.
4.
2.
In the Alias name field, enter the name of the alias you want to unregister.
Select the engines from which to unregister the specified alias.
Click OK.
Viewing Registrations for an Engine
The registration procedures described in the previous sections let you perform registration and unregistration of iIS distributions on an environment-wide basis, that is, for multiple engines within an environment. However, iIS Console lets you view registration status only for individual engines.
For any engine, you can view the user profiles, validation, assignment rule dictionaries, process definitions, and aliases that are registered with that engine.
You can also unregister any distribution registered with the engine. In the case of process definitions, you can monitor all instances of a registered process definition.
150 iPlanet Integration Server • Process System Guide • August 2001
Viewing Registrations for an Engine
➤
To view the registrations for a given engine
1.
Select a running engine in the iIS Console main window.
2.
Choose Monitor > Registrations, or choose Registrations from the popup menu.
The Registrations window displays:
3.
4.
Click a tab to view a particular type of registered distribution.
Check that the window’s refresh options are appropriately set.
Unregistering a Distribution
From the Registrations window, you can unregister any distribution currently registered with an engine, except a validation. As with the environment-wide registration facilities, you can only unregister one distribution at a time.
➤ To unregister a registered distribution
1.
Select a running engine in the iIS Console main window.
2.
Choose Monitor > Registrations, or choose Registrations from the popup menu.
The Registrations window displays.
Chapter 5 Managing Registrations 151
Viewing Registrations for an Engine
3.
4.
Click a tab to open it to view a particular type of registered distribution.
The menu bar changes depending on the type of registration you are viewing.
For example, if you are viewing assignment rule distributions, you see the File,
View, and Assignment Rule menus. In the next step, the menu that changes is referred to as the TabName menu.
Select the item to unregister and choose TabName > Unregister.
NOTE You cannot unregister a validation. A validation is automatically deleted when a new validation is registered.
Monitoring Instances of a Registered Process
Definition
From the Registrations window, you can monitor instances of any registered process definition.
NOTE You can also monitor instances of a registered process definition using the Monitor > Processes Resident command of iIS Console.
However in this approach you get a list of all executing process instances in an engine, so you have to filter the resulting list by process name. In the procedure below you start with a list of only those process instances that correspond to a given registered process definition.
➤
To monitor instances of a registered process definition
1.
Select a running engine whose process instances you want to monitor in the iIS
Console main window.
2.
3.
Choose Monitor > Registrations.
The Registrations window displays with the Process Definitions tab open.
Select the registered process definition whose instances you want to monitor.
152 iPlanet Integration Server • Process System Guide • August 2001
Performing Application Upgrades
4.
Right-click and choose Process Definition > Open from the popup menu.
The Processes Resident window displays:
By selecting a process instance in the window and opening it (double-click or use the mouse popup menu), you can get the process instance’s activity list, timer list, process attribute list, and so on. From these lists, in turn, you can get information about the state of any activity, timer, or process attribute.
Performing Application Upgrades
If the process logic of a business process application changes, you might need to upgrade process definitions, assignment rule dictionaries, user profiles, and validations—and even client applications or application proxies—depending on the type of change involved.
While properly specifying the upgrade of an iIS enterprise application is the responsibility of an application system designer, it is helpful for a system manager to understand the issues involved.
Under normal conditions, upgrading consists of registering new or updated process definitions to accommodate changes in the business process. This type of upgrade is straightforward.
In some situations, the new or updated process definitions might be based on new or modified assignment rules. In that case a new or modified assignment rule dictionary might have to be registered as well. (In some cases, you only have to register new or modified assignment rule dictionaries because the process definitions do not change.)
Chapter 5 Managing Registrations 153
Performing Application Upgrades
However, sometimes an upgrade involves a new or modified extended user profile. If this is the case, then the user profile, the validation and the assignment rule dictionaries that depend upon it, and client applications that reference it might all need to be upgraded. This type of upgrade has a broader impact, especially if you cannot shut down your engine to perform the upgrade.
Monolithic Upgrades
In a monolithic upgrade, your developers create an upgraded user profile and validation, upgraded assignment rule dictionaries, and upgraded client applications that are not compatible with the earlier versions. You must shut down your business process application to perform the upgrade.
➤
To perform a monolithic upgrade
1.
All client applications and application proxies must close their sessions with the engine and shut down.
2.
3.
4.
5.
6.
Unregister current assignment rule dictionaries and the user profile.
The validation does not need to be unregistered (in fact, it cannot be). Do not unregister process definitions.
Deploy each upgraded client application to all nodes supporting that client application.
Register the upgraded user profile, validation, and assignment rule dictionaries.
Register upgraded process definitions, if an upgrade is necessary.
Users can then start their upgraded client applications, open sessions with the engine, and resume work.
154 iPlanet Integration Server • Process System Guide • August 2001
Performing Application Upgrades
Rolling Upgrades
Rolling upgrades must be used in production situations where work cannot be interrupted and client applications cannot be upgraded monolithically. In a rolling upgrade, the changeover from an earlier version to an upgraded version takes placed gradually. It requires that the engine simultaneously support client applications based on the earlier user profile as well as on the updated user profile.
To support differing versions of a user profile, designers create upgraded versions of the validation and the assignment rules that can accommodate both the new and old user profiles. Client application developers can then create new client applications based on the new user profile.
➤
To perform a rolling upgrade
1.
Register the upgraded user profile, validation, and assignment rule dictionaries.
2.
Deploy each upgraded client application to nodes supporting that client application.
3.
When they choose to upgrade, users close sessions with the engine, shut down their old client applications, start up their new, upgraded client applications, open sessions with the engine, and resume work.
Chapter 5 Managing Registrations 155
Performing Application Upgrades
156 iPlanet Integration Server • Process System Guide • August 2001
Chapter 6
Managing Process Execution
The main function of an iIS process engine is to coordinate the work done by a variety of users (or application components) in performing the activities that comprise a business process. The engine does this by executing iIS process definitions that have been registered with the engine.
Managing process execution in an iIS system involves monitoring various aspects of process execution and making administrative adjustments if necessary.
This chapter first discusses the iIS process execution life cycle—from process creation to process termination—and then describes how to monitor and manage this process execution. The specific tasks covered include:
• monitoring and managing engine sessions
• monitoring and managing process execution
• providing historical analysis of process execution activity
• monitoring and managing two-phase commit transactions
Introduction
An iIS process engine creates instances of various process definitions and executes them from start to finish. During process execution, a succession of activities specified by the process definition are performed by client applications—or applications accessed through proxies—that have opened sessions with the engine.
The engine manages and tracks these activities to their final completion, ensuring that they are performed in proper sequence.
This section discusses two topics basic to understanding process execution: engine sessions and activity states. More detailed information about process execution is provided in
“Process Execution” on page 165 .
157
Introduction
Engine Sessions
An iIS process engine generally coordinates the work of a number of applications that perform various activities that comprise a business process. To manage this process flow, the engine needs to maintain sessions with each of the applications involved. Consequently, the first order of business of a client application or application proxy is to establish a session with any engines managing activities to be performed by the corresponding application.
NOTE In the remainder of this chapter—unless explicitly stated—the term
“client application” applies to client applications developed using iIS process client APIs, and also to application proxies used to integrate existing applications through backbone system capabilities provided by iIS. The application proxy interacts with an engine in the same way a client application does.
When a client application attempts to open a session with an engine, the engine must verify the authenticity of the application or user. This validation is performed by the engine using logon information provided by the application or user and validation code in the validation registered with the engine. This validation code normally compares information provided by the user with information stored in an organization database.
The session is the mechanism for all communication between a client application and the engine. It is used by the engine to offer activities in a process to different applications or users and to notify them about changes in the status of these activities. It is used by the client application to accept activities to perform and notify the engine when work on an activity is complete.
A session can have the following states:
Session state
ACTIVE
SUSPENDED
Description
A session to which the engine can assign activities and post events.
A session previously active, but now dormant.
This state can result from a lost connection between client application and engine, or from explicit action by a system manager or client application user. The engine cannot assign new activities to a suspended session or post events to it.
158 iPlanet Integration Server • Process System Guide • August 2001
Introduction
Session state
RECONNECTION_IN_PROGRESS
Description
During engine recovery, a previously active session that is waiting to be restored to active during the engine recovery.
An ACTIVE or SUSPENDED session can be terminated by an application or user, or by a system manager. A RECONNECTION_IN_PROGRESS session can be suspended or terminated by a system manager. A session that has been terminated is deleted from the engine and the engine’s current state database table.
Disrupted Sessions
A session is a two-way communication between client application and engine. Both the client application and the engine maintain an object representing the session.
The state of the engine object determines the state of the session. The client application’s session object uses code in the client API to restore the connection when a temporary disruption occurs. (A temporary disruption can be due to network interruptions or engine failure.)
The client session object tests the connection to the engine at regular intervals (refer to the iIS online help for the WFSession.SetPingInterval). When the client session object detects a disruption in the connection between the client application and the engine, it automatically attempts to restore the connection. If the client session object is unsuccessful in restoring the connection within a specified auto reconnect
timeout period, it notifies the client application that the connection has been permanently lost. The auto reconnect timeout period is configured in a client application using the WFSession methods SetRetry and SetPingInterval.
Network failure The engine does not know about a network interruption until it touches an engine session object, for example, to post an event or assign an activity.
If the engine finds the session disrupted, the engine suspends or terminates the session, depending on the value of the session’s disconnect action property (set using the control parameter to WFEngine.OpenSession or WFSession.SetControl).
Engine failure When a primary engine unit fails, all active sessions are automatically set to RECONNECTION_IN_PROGRESS. During recovery, sessions remain in this state for a specified timeout period (set in the engine’s configuration), waiting for the client sessions to reconnect. During this period, a system administrator can suspend or terminate these sessions.
Chapter 6 Managing Process Execution 159
Introduction
If the client session reconnects to the engine during the timeout period, the sessions are restored depending on the value of the session’s reconnect action property (set using the control parameter to WFEngine.OpenSession or WFSession.SetControl).
If the client session fails to reconnect, the sessions are suspended or terminated, according to the specification in the engine configuration.
If failover occurs (the partner engine unit comes ONLINE) within the auto reconnect timeout period, the client attempts to restore the sessions according to the value of the session’s reconnect action property.
If the reconnect action property is set to RECONNECT_ALLOWED, then the session is restored to ACTIVE state. If the reconnect action property is set to
RECONNECT_PROHIBITED, the session is not restored.
Session disconnect and reconnect parameters are summarized in the table below.
Session Property Value disconnect action SUSPEND
Description
Engine suspends session if it finds a disruption in the connection between it and the client application.
reconnect action
TERMINATE
RECONNECT_ALLOWED
Engine terminates session if it finds a disruption in the connection between it and the client application.
Allows client API code or a client application to restore a suspended session to ACTIVE state.
RECONNECT_PROHIBITED Prohibits client API code or a client application from restoring a suspended session to ACTIVE state.
A new session must be created to replace the suspended session.
When the client API auto-reconnect mechanism attempts to restore a suspended session to an ACTIVE state, it passes the user name, password, and session name to the engine that was used in establishing the original session. (The client API stores this information.) The engine uses this information to confirm which suspended session should be restored to ACTIVE and whether the reconnection is allowed.
160 iPlanet Integration Server • Process System Guide • August 2001
Introduction
If a connection is permanently lost, the client API code notifies the client application that its connection has been permanently lost. The client application must explicitly reopen its session to restore it to ACTIVE state. Its ability to restore a suspended session to an ACTIVE state depends—just as with the auto-reconnect mechanism—on the value of the session’s reconnectAction property set when the session was first opened.
Explicitly Suspended Sessions
When a system manager explicitly suspends one or more sessions or changes the state of a primary engine unit from ONLINE to STANDBY, all affected sessions are automatically suspended and their corresponding client applications notified through an event. If the engine unit (or its partner) is subsequently restored to
ONLINE state, the sessions are not automatically restored to ACTIVE state. After sessions are explicitly suspended, the corresponding client applications must explicitly reopen their sessions or create new sessions, depending on the values of the reconnectAction property set when each session was originally opened.
The effect of suspending a session on any activities a client application is performing (that is, on ACTIVE activities) depends on the suspendAction property set by the client application when it accepts the activity. For more information, see the description of the WFActivity method StartActivity in the iIS Process Client
Programming Guide.
Explicitly Terminated Sessions
When a system manager explicitly terminates one or more sessions, all such sessions are automatically terminated and their corresponding client applications are notified through an event. Termination ends sessions and deletes them from the engine and the engine’s current state database table. After sessions are terminated, the corresponding client applications must explicitly open new sessions.
NOTE Terminating a session on any activities a client application is performing (that is, on ACTIVE activities) aborts the activities. If an activity does not have an OnAbort router to accommodate an
ABORTED state (see “Activity States”
below), the engine aborts the process instance. You should therefore undertake the termination of sessions with caution.
Chapter 6 Managing Process Execution 161
Introduction
Activity States
During process execution the engine manages a succession of activities through a number of states, from creation to deletion. While there are a number of activity types, each with its own properties and behavior (see
states shown in the following table and illustrated in
more detailed information on engine operations within each state and on transitions between states, see
“Activity Execution” on page 168 .)
Activity state
PENDING
READY
Description
An activity is normally created and placed in PENDING state when the router method of a completed (or aborted) activity or of an expired timer names the new activity. The activity remains in the pending state until all trigger conditions are met, at which time the engine performs any work specified by a Ready method in the process definition and then places the activity in READY state.
When an activity is placed in READY state, it is made available to client sessions based on assignment rules specified for the activity in the process definition. Depending on the type of activity, the engine either offers it to each session whose user profile matches one or more of the activity’s assignment rules (offered activity), places the activity in a queue (queued activity), or places it directly in ACTIVE state (automatic activity). When offered to a session, the activity is placed on the session’s activity list (a list of offered activities maintained by the engine for each session) and is then available to the session’s client application. When placed in a queue, the activity is available to any session whose user profile matches one or more of the activity’s assignment rules.
162 iPlanet Integration Server • Process System Guide • August 2001
Introduction
Activity state
ACTIVE
COMPLETED
ABORTED
Description
When a client application accepts an offered activity or takes it off a queue, it is placed in ACTIVE state. The engine performs any work specified by an OnActive method in the process definition and then provides the client application with process attribute data needed to perform the activity. The client application is responsible for performing the work associated with the activity. When the client determines that the work is complete, it informs the engine, which removes the activity from the session’s activity list and places the activity in a COMPLETED state. When the client aborts the activity, it informs the engine, which removes the activity from the session’s activity list and places the activity in an ABORTED state.
The COMPLETED state signifies successful completion of an activity.
The engine performs any additional work specified by the
OnComplete method in the process definition, and then executes the activity’s OnComplete router methods. Once any successor activities specified in the routers are created, the engine deletes the
COMPLETED activity from memory.
The ABORTED state signifies unsuccessful completion of an activity.
The engine performs any additional work specified by the OnAbort method in the process definition, and then executes the activity’s
OnAbort router methods. Once any successor activities specified in the routers are created, the engine deletes the ABORTED activity from memory. If the process definition does not provide OnAbort routers and the activity is aborted from ACTIVE state, the engine will abort the process instance.
Chapter 6 Managing Process Execution 163
Introduction
Figure 6-1 Activity State Transitions—from Creation to Termination
Activity State
PENDING
READY
ACTIVE
ABORTED
COMPLETED
Process Execution Step
Activity referenced by router of another activity
Engine activates timer controls, if any.
Engine executes Trigger method.
If Trigger method returns TRUE, Engine executes Ready method, if any.
Ready method finishes
Engine activates timer controls, if any.
Engine offers activity to sessions/queues
(offered or queued activity).
Client accepts activity
Engine activates timer controls, if any.
Engine executes OnActive* method, if any.
Client (or engine) performs activity.
Client completes or aborts activity
Engine activates timer controls, if any.
Engine executes OnComplete method, if any.
Engine executes OnComplete router methods.
Engine executes OnAbort method, if any.
Engine executes OnAbort router methods.
* If an OnActive method returns TRUE, execution contines normally.
If an OnActive method returns FALSE, then the activity is aborted.
164 iPlanet Integration Server • Process System Guide • August 2001
Process Execution
Activity Types
A process definition can include a number of different activity types, each of which passes through the various activity states in a different fashion. The table below summarizes the different types of activities. For more information on activities, see the iIS Process Development Guide.
Activity type
First
Offered
Queued
Subprocess
Automatic
Last
Description
Specialized activity: the first activity in a process definition.
Automatically placed in COMPLETED state, bypassing the PENDING,
READY, and ACTIVE states.
An activity performed by client applications. Offered to sessions based on assignment rules and accepted by a client application from its work list. Passes through all states.
An activity performed by client applications. Placed on a queue and accepted by a client application. Passes through all states.
Represents a separate process executed by an engine. Passes directly from PENDING to ACTIVE state, bypassing the READY state.
An activity performed directly by the engine. Not assigned to sessions.
Passes through all states.
Specialized activity: the last activity in a process definition. Passes directly from PENDING to a COMPLETED state, bypassing the intermediate states.
Process Execution
This section discusses how an engine executes an iIS process definition. Each process executes through a life cycle consisting of process instance creation, process instance execution, and process instance termination. Each of the six activity types—First, Offered, Queued, Subprocess, Automatic, and Last—plays a specific role in the overall life cycle.
Process instance creation Process creation involves the creation of a First activity.
Chapter 6 Managing Process Execution 165
Process Execution
Process instance execution Process execution involves creation of any number of activities, including one or more Offered activities (which are offered to and performed by client applications), Queued activities (which are placed on a queue and performed by client applications—but not, in this case, by applications integrated through proxies), Subprocess activities (which create an instance of another process), and Automatic activities (which are performed by the engine rather than client applications).
Process instance termination Process termination involves the completion of a
Last activity.
The different activity types are discussed in the context of each stage of the execution life cycle, explained in more detail in the sections below.
Process Instance Creation
The engine creates a new instance of a process in three situations:
• A client application requests a new instance of a process
The request must provide the name of a process definition registered with the engine. The engine invokes the assignment rules for process creation to determine if the user making the request is authorized to create an instance of the process. If so, a First activity is created. A First activity passes automatically through the PENDING, READY, and ACTIVE states, and is placed directly into a COMPLETED state. Its OnComplete router methods, if any, are executed, and process execution proceeds.
• A Subprocess activity becomes ACTIVE
A Subprocess activity specifies a process and engine name. If the specified process is registered with the specified engine and all the required data can be located, the specified engine creates a new instance of the process. As in the previous case, a First activity is created, and process execution then proceeds.
• An engine recovers current state
During a failover scenario, or whenever a backup engine unit comes online, the engine needs to recover current state information from the engine database. In this situation, process instances that were active when the engine went off line are recreated and restored to their former states.
166 iPlanet Integration Server • Process System Guide • August 2001
Process Execution
Process Instance Execution
Process execution consists of the sequential creation, execution, and termination of the activities specified in a process definition. When an activity is created, it remains in a PENDING state until its trigger conditions are fulfilled. In general, the activity then passes through READY and ACTIVE states, as shown in
Figure 6-1 on page 164 , to a COMPLETED state. When the activity is completed, its router
methods are executed and succeeding activities are created, continuing the process execution process.
The activity creation, execution, and termination stages are each discussed below.
Activity Creation
The engine creates an instance of an activity in the following situations:
• A new process is created—the engine creates a First activity, passes it through
PENDING, READY, and ACTIVE states, and places it directly into a
COMPLETED state.
• A completed activity’s router points to an activity and the router method returns TRUE.
• An aborted activity’s router points to an activity and the router method returns
TRUE.
• An expired timer’s router points to an activity and the router method returns
TRUE.
In the last three cases, the engine creates an activity, and places in a PENDING state. However, if the target activity already exists in a PENDING state, a new instance is not created. (If the activity already exists in a READY or ACTIVE state, a new instance is created and placed in a PENDING state.)
The engine executes the trigger method of a PENDING activity in the following situations:
• The activity is first created
• The router method of a router pointing to the activity returns TRUE
• A process attribute for the process instance changes value
Chapter 6 Managing Process Execution 167
Process Execution
Activity Execution
As a general rule, activity execution consists of taking each activity through the series of states described in
“Activity States” on page 162 . In each state, the engine
performs a number of operations before the activity transitions to the next state. As each state transition takes place, the new state is written into memory and logged in the state database tables. The engine activates any timer controls referenced by the new state and executes one or more activity methods that may be defined for that state in the process definition, as shown in
executing activity methods, the engine applies the process attribute locks specified for those methods in their respective attribute access lists, as defined in the process definition.
Despite these general rules, activity execution also depends to some degree on the type of activity being executed. The four types of activities that require work to be performed—Offered, Queued, Subprocess, and Automatic—are all executed somewhat differently by an iIS process engine. Execution of each activity type is discussed separately below.
Offered Activities
Transition to READY State When the trigger conditions are met, the engine performs any work specified in the Ready method (if one exists in the process definition) and places the activity in a READY state.
READY State Handling When an Offered activity is placed in a READY state, the engine offers the activity to sessions (that is, offers it to clients) based on the activity’s assignment rules.
During assignment, the engine searches for eligible sessions. The engine offers the activity to sessions based on the activity’s assignment rules (for example, to each session for which the session’s user profile matches at least one of the activity’s assignment rules). The engine continues assignment until all active sessions have been examined.
When an Offered activity is assigned to a session, it is placed on an activity list maintained by the engine for that session—the session activity list.
168 iPlanet Integration Server • Process System Guide • August 2001
Process Execution
Session assignment takes place in any of the following situations:
• An offered activity is placed in a READY state for the first time.
• An offered activity is rolled back from an ACTIVE state to a READY state—can occur if a client application rolls the activity back to READY state (discards any work performed on the activity), if a system manager rolls the activity back to
READY state in order to force it to be reassigned, or if the activity is being performed by a session that is suspended and the client has set the suspendAction property to REMOVE (that is, remove the activity from the session’s activity list if the session is suspended).
• A new session is opened (or reverts from SUSPENDED to ACTIVE)—the engine examines the list of READY Offered activities and assigns them to the newly active session based on each activity’s assignment rules.
Transition to ACTIVE State The engine places an Offered, READY activity in an
ACTIVE state when a client application accepts the corresponding work item. The engine removes the activity from all sessions to which it is assigned except the one which accepts the corresponding work item.
The engine provides the client application with the associated application dictionary item (a reference to the application or service needed to perform the activity, a description of the work to be performed, and any required process attribute data). The engine ensures that any required process attributes are locked so that no other session can access them during performance of the activity.
ACTIVE State Handling The engine performs any work specified in the
OnActive method (if one exists in the process definition).
The client application that accepted the activity is responsible for completing the work associated with the activity. When the client determines that the work is complete, it informs the engine, which removes the activity from the session’s activity list and places the activity in a COMPLETED state.
The client can abort work by requesting that the engine place the activity in an
ABORTED state, or the client can also reset the activity to READY state (discarding any work performed on the activity, including changes in attribute values).
Queued Activities
Transition to READY State When the trigger conditions are met, the engine performs any work specified in the Ready method (if one exists in the process definition) and places the activity in READY state.
Chapter 6 Managing Process Execution 169
Process Execution
READY State Handling When a Queued activity is placed in a READY state, the activity is placed in a queue named after the queued activity and containing activities with the same name from multiple process instances. Client applications access the queue, and accept the highest priority activity on the queue. The priority ordering of activities in a queue can depend on the value of a queue prioritizing process attribute. If so, the queue is dynamically reordered whenever an activity is added to the queue and whenever the prioritizing process attribute changes value.
Transition to ACTIVE State The engine places a queued, READY activity in an
ACTIVE state when a client application accepts the activity, then removes the activity from the top of the queue. When a client application accepts an activity, the engine evaluates the corresponding session against the activity’s assignment rule to confirm that the client application is eligible to perform the activity.
The engine provides the client application with the associated application dictionary item (a reference to the application or service needed to perform the activity, a description of the work to be performed, and any required process attribute data). The engine ensures that any required process attributes are locked so that no other session can access it during performance of the activity.
ACTIVE State Handling The engine performs any work specified in the
OnActive method (if one exists in the process definition).
The client application that accepted the activity is responsible for completing the work associated with the activity. When the client determines that the work is complete, it informs the engine, which removes the activity from the session’s activity list and places the activity in a COMPLETED state.
The client can abort work by requesting that the engine place the activity in an
ABORTED state, or the client can also reset the activity to a READY state
(discarding any work performed on the activity, including changes in attribute values).
Subprocess Activities
Transition to READY State In this case the activity skips READY state and is placed directly in an ACTIVE state.
READY State Handling A subprocess activity passes directly from a READY to an ACTIVE state without being assigned to sessions.
Transition to ACTIVE State In the case of a subprocess activity, the engine places the activity directly in an ACTIVE state from a PENDING state. It skips a
READY state altogether.
170 iPlanet Integration Server • Process System Guide • August 2001
Process Execution
ACTIVE State Handling The engine performs any work specified in the
OnActive method (if one exists in the process definition).
An active subprocess activity is handled differently depending on whether the subprocess activity is synchronous or asynchronous.
• Synchronous—waits for completion of the new process:
If the subprocess activity is synchronous and if the new process is successfully created, the subprocess activity remains in an ACTIVE state (in the parent process), awaiting completion of the subprocess. If the subprocess fails to complete for any reason, the subprocess activity is placed in an ABORTED state.
• Asynchronous—does not wait for completion of the new process:
If the subprocess activity is asynchronous and if the new process is successfully created, the subprocess activity is placed in a COMPLETED state (in the parent process). If the subprocess is not successfully created, the subprocess activity is placed in an ABORTED state.
Automatic Activities
Transition to READY State When the trigger conditions are met, the engine performs any work specified in the Ready method (if one exists in the process definition) and places the activity in a READY state.
READY State Handling An automatic activity passes directly from a READY to an ACTIVE state without being assigned to sessions.
Transition to ACTIVE State In the case of an automatic activity, the engine places the activity directly in an ACTIVE state from a READY state without assigning it to sessions because the work of the activity is invoked or performed by the engine rather than by a client application.
ACTIVE State Handling The engine performs the automatic activity’s OnActive method when the activity is placed in an ACTIVE state. The work performed by the activity is invoked or coded in the OnActive method within the process definition. When the OnActive method is fully executed and returns TRUE, the activity is placed in a COMPLETED state.
Activity Termination
Activity termination occurs when the engine places an activity in either a
COMPLETED state or an ABORTED state.
Chapter 6 Managing Process Execution 171
Process Execution
Completed Activities
When an engine places an activity in a COMPLETED state, the engine performs the following actions:
• executes the activity’s OnComplete method, if one is specified in the process definition
• executes the activity’s OnComplete router methods
• checks for a process stall condition—when no other activities are in an ACTIVE or READY state (that is, all are either COMPLETED or PENDING) and no timers are active—and aborts the process instance if a stall condition is detected
• deletes the COMPLETED activity from state information
In the case of a Last activity, however, instead of performing the above actions, the engine places the process directly in a COMPLETED state.
Aborted Activities
When an engine places an activity in an ABORTED state, the engine performs the following actions:
• executes the activity’s OnAbort method, if one is specified in the process definition
• executes the activity’s OnAbort router methods—if none are specified, the engine will, by default, abort the process instance
• checks for a process stall condition (no other activities are in an ACTIVE or
READY state—that is, all are either COMPLETED or PENDING—and no timers are active) and aborts the process instance if a stall condition is detected
• deletes the ABORTED activity from state information
In the case of First and Last activities, however, the activities cannot reach an
ABORTED state, since they proceed directly to a COMPLETED state.
172 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Engine Sessions
Process Instance Termination
Process termination occurs when the engine places a process instance in either a
COMPLETED state or an ABORTED state.
Completed Process Instances
An engine completes a process instance when the Last activity reaches a
COMPLETED state.
Aborted Process Instances
An engine aborts a process instance in the following situations:
• the process instance is stalled—no activities are in an ACTIVE or READY state
(that is, all are either COMPLETED or PENDING) and no timers are active.
• an ACTIVE activity (including a Subprocess activity) is placed in an ABORTED state and has no OnAbort router method specified.
• a system manager requests that a process be aborted.
• an exception is thrown on an activity method.
When a process instance is aborted, any uncompleted activities in the process are aborted, all process timers are stopped, and all process attribute updates are discarded.
Monitoring and Managing Engine Sessions
Since the engine is coordinating work being performed by client applications that have sessions with the engine, one dimension of system management concerns the number and state of such sessions.
This section describes how to perform the following tasks:
• Monitor the state of a session
• Manage one or more sessions
NOTE This section uses mouse popup menu commands to describe how to perform various operations. You can also use other methods of accessing commands, as described in
Chapter 6 Managing Process Execution 173
Monitoring and Managing Engine Sessions
Monitoring the State of a Session
Often you want to know information about a particular session, such as its state, its creation time, the list of activities assigned to the session, or information about any such assigned activities that are in ACTIVE state.
➤
To obtain state information about a session
1.
Open the iIS Console and select the engine to monitor.
2.
Choose Monitor > Sessions, or choose Sessions from the popup menu.
This opens the list of current sessions.
For each session in the list, the window displays an ID, the user who opened the session, the state of the session, and the number of items on the session’s activity list.
174 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Engine Sessions
3.
To get more information about a session, select it, and choose Session > Open from the popup menu.
An activity list for the session is displayed.
For each activity in the list, the dialog displays the activity ID, the process name and process instance ID in which it was created, and its current state.
NOTE To get more information about a given activity, such as how long the activity has been in the present state, and information about the corresponding process instance (process attributes, activities, timers, and so on), see
Chapter 6 Managing Process Execution 175
Monitoring and Managing Engine Sessions
Managing Sessions
Session management consists of suspending or terminating sessions, or sending a message to one or more sessions (that is, the corresponding client applications).
Suspending or Terminating Sessions
On occasion you might find it necessary to suspend or terminate one or more active sessions. Suspending a session posts a SessionSuspended event, and terminating the session posts a SessionTerminated event. These events allow the client application to handle the state change gracefully.
For the impact of suspending a session, see
NOTE A session that has in-progress two-phase commit operations can be suspended, but cannot be terminated. For more information, see
“Monitoring and Managing Two-Phase Commit” on page 199 .
➤
To suspend a session
1.
Choose Monitor > Sessions to display the Sessions window with the list of current sessions for the engine.
2.
Select the session to suspend.
3.
Choose Session’Name’ > Suspend from the popup menu.
You will be asked to confirm the suspension.
NOTE To suspend all sessions, choose Session > Suspend all.
176 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Engine Sessions
➤
To terminate a session
1.
Choose Monitor > Sessions to display the Sessions window with the list of current sessions for the engine.
2.
Select the session to terminate.
3.
Right-click and choose Session’Name’ > Terminate from the popup menu.
You will be asked to confirm the termination.
NOTE To terminate all sessions, choose Session > Terminate all.
Sending and Broadcasting Messages to Sessions
You can send an informational message to any active session or broadcast the same message to all active sessions. A client application can watch for messages posted to its corresponding engine session.
➤ To send a message to an active session
1.
Choose Monitor > Sessions to open the list of current sessions for the engine.
Chapter 6 Managing Process Execution 177
Monitoring and Managing Engine Sessions
2.
Open the session of interest.
3.
Click Send Message. The Send Message window displays:
4.
5.
6.
Type the message in the Message field.
Select the urgency: Informational or Critical.
Click Send.
178 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
➤
To broadcast a message to all sessions
1.
Choose Monitor > Sessions to open the list of current sessions.
2.
Right-click and choose Session > Broadcast from the popup menu. The
Broadcast Message window displays.
3.
4.
5.
Type the message in the Message field.
Select the urgency: Informational or Critical.
Click Send.
Monitoring and Managing Process Execution
As described in
“Process Execution” on page 165 , an iIS process engine executes
process instances by creating a succession of activities, moving them through a number of states, checking timers, and locking, modifying, and unlocking process attributes.
The engine maintains information about all registered process definitions and the process instances corresponding to each. For each process instance, it maintains information about activities, timers, and process attributes (and locks placed on each process attribute). The information provided about these objects and their
relationship to one another are illustrated in Figure 6-2 :
Chapter 6 Managing Process Execution 179
Monitoring and Managing Process Execution
Figure 6-2 Process Execution Objects: Properties and Relationships
Session
Activity list
Session id
Session name
User
Status
Transaction id
Activity Instance
TimerLink list
Activity state
Activity name
Type
Asignment list
Process id
Attribute list
Process Instance
Creation time
Process id
Activity list
Attribute list
Timer list
Process Attribute
Value
Lock state
Timer Instance
Process id
Timer name
Timer state
Expiration time
Parent activities
Using the iIS Console, you can display lists of these objects and filter them according to specific criteria. You can also open and view the properties (or state) of any specific process instance, activity instance, timer instance, or process attribute. In addition, There are a number of situations where you might want to intervene in process execution to resolve problems.
This section describes a number of common process execution monitoring and management tasks you might perform: process instance Checking the execution status of a process instance and possibly aborting it.
activity Checking the status of an activity instance and possibly changing its state.
180 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution activity queue Checking the status of an activity queue and possibly reprioritizing an activity within the queue (for queued activities only).
timer Checking the status of a timer instance and resetting it or changing its state.
process attribute Checking the value and lock state of a process attribute and possibly changing its value and removing a lock.
In addition, you typically check for bottlenecks in process execution and diagnose their cause.
Managing Process Instances
This section describes how to check the execution status of a process instance and possibly abort it.
Checking the Status of a Process Instance
Suppose you want to find out the current execution status of a given process instance: which of its activities are in PENDING, READY, or ACTIVE state; how long they have been in those states; the values of important process attributes; and the state of process timers.
➤ To check the current execution status of a process instance
1.
Select the engine executing the process in the iIS Console main window.
The engine must be running.
2.
Choose Monitor > Processes Summary. The Processes Summary window displays, showing the list of process definitions, by name, for which there is at least one active process instance being executed by the engine.
For each process instance, the window displays the process name, the version of the process definition, and the number of process instances being executed.
Chapter 6 Managing Process Execution 181
Monitoring and Managing Process Execution
3.
Select the process name you want to view instances of and choose Processes >
Open Instances of.
This opens the Processes Resident window, displaying the list of process instances being executed by the engine for the selected process name.
For each process instance the window displays the process name, the version of process definition, the value of the primary process attribute, the primary process attribute name, the process instance ID, and the process instance creation time.
NOTE You can open the Processes Resident window more directly by choosing Monitor > Processes Resident, however the instances displayed correspond to all process definitions rather than to a single one.
4.
Search for a process instance by process attribute value, creator, or creation time.
You can use the Filter or Sort commands, available from the View menu, to help find specific process instances. For more information, refer to
“Filtering iIS Console Lists” on page 73
and
“Sorting iIS Console Lists” on page 76 .
182 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
5.
Select a process instance and choose Process > Open Instance.
The Process Instance property inspector is displayed.
By selecting the appropriate tab, you can get the process instance’s activity list, timer list, process attribute list, and other information. From these lists, in turn, you can get information about the state of any activity (see
Status of an Activity” on page 185 ), timer (see
“Checking the Status of a Timer” on page 191
), or process attribute (see “Checking the Value and Lock State of a
Process Attribute” on page 193 ).
Chapter 6 Managing Process Execution 183
Monitoring and Managing Process Execution
Aborting a Process Instance
If you want to stop execution of a process instance, you can abort that process instance. This aborts all uncompleted activities, stops all timers, and discards all process attribute updates.
➤
To abort a process instance
1.
Open the property sheet of the process instance you want to abort.
2.
under “Checking the Status of a Process Instance” on page 181 .
Click the Abort Process button.
NOTE You can abort all process instances displayed in a Processes
Resident window by choosing Process > Abort All. If an error is encountered you are asked if you want to continue aborting the remaining processes or stop the operation.
184 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
Managing Activity Instances
This section describes how to check the status of an activity and change its state.
Checking the Status of an Activity
1.
Select the activity in any window that contains an activity list:
❍
Process Instance property inspector
❍
❍
Session property inspector
Activities Resident window
❍
Activity Queues window
An example activity list (the Activities tab of a Process Instance property inspector) is shown below.
Chapter 6 Managing Process Execution 185
Monitoring and Managing Process Execution
2.
Choose Activities > Open.
The Activity property inspector displays:
The property inspector consists of a number of tabs: the Info tab displays the basic properties of the activity, and additional tabs provide information such as the sessions to which the activity is assigned, the current value of process attributes, and information about timers linked to the activity.
For example, if you click the Process Attributes tab, you get information about the current values of the process attributes for the process instance in which the activity was created.
NOTE You can click the Process button on the Activity property inspector to display the Process Instance property inspector.
Changing the State of an Activity
You can make the following state changes for an activity:
• from PENDING to READY
You might do this because one of the trigger conditions cannot be met for some reason, but you want the activity to go to the READY state anyway.
186 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
• from ACTIVE to READY
You might do this because the person working on an activity cannot complete it and you want it to be reoffered to other users. All process attributes are unlocked and rolled back to the values they had when the activity was first offered.
• from PENDING or READY to ABORTED
You might do this because some condition has arisen that precludes the completion of the activity and you want the OnAbort routing, if any, to take place. If there are no OnAbort routers or if all OnAbort routers return FALSE, the activity is simply aborted and any locked process attributes are unlocked.
• from ACTIVE to ABORTED
You might do this because some condition has arisen that precludes the completion of the activity and you want the OnAbort routing, if any, to take place. If there are no OnAbort routers or if all OnAbort routers return FALSE, not only is the activity itself aborted, but the whole process instance is aborted.
You cannot abort an ACTIVE synchronous subprocess activity—the activity is waiting for a subprocess to either complete or abort.
CAUTION Use caution when aborting an ACTIVE activity.
➤
To change the state of an activity
1.
Open the property inspector for the activity whose state you want to change.
2.
“Checking the Status of an Activity” on page 185
.
Click the Set State button.
The Set Activity State window displays, with the current state filled in.
Chapter 6 Managing Process Execution 187
Monitoring and Managing Process Execution
3.
4.
From the New state drop list, select the new state of the activity.
Click the Set button.
Managing Activity Queues
This section describes how to check the status of an activity queue and how to reprioritize an activity within the queue. Activity queues only apply to queued activities.
Checking the Status of an Activity Queue
Occasionally you might need to check the queues that store queued activities until users are ready to work on them. You can display a list of activity queues and open a queue to display the contents of the queue. Doing so might tell you, for example, that a particular activity is not being performed because it remains at the bottom of a queue.
➤ To view the contents of an activity queue
1.
Select the engine maintaining the activity queue in the iIS Console main window.
The engine must be running.
2.
Choose Monitor > Activity Queues. The Activity Queues window displays, showing the list of queues in the engine:
For each queue, the window displays the process name and queue name
(which is the same as the name of the queued activity), the number of activities in the queue, and/or the number of sessions waiting for an activity to be placed in the queue.
188 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
3.
4.
Select a queue.
Choose Queue > Open. The Activity Queues window displays, showing the list of activities in the queue.
For each activity in the queue, the window displays the activity name, activity
ID, activity state, prioritizing value (value of the queue prioritizing process attribute), and process ID.
If you want more information about an activity in the queue, you can open the activity property inspector by selecting the activity and choosing Activity > Open
(see
“Checking the Status of an Activity” on page 185 ). If you want to change the
position of an activity in the queue, see
“Reprioritizing a Queued Activity,” below.
Reprioritizing a Queued Activity
If a queued activity is not making it to the top of an activity queue because the value of its queue prioritizing process attribute always places it toward the bottom of its queue, you can change the value of the process attribute to reprioritize the activity in the queue. You must be careful when performing this operation, however, since other process logic might also depend on the value of the process attribute.
➤
To reprioritize a queued activity
1.
Open the Activity Queue window for the queued activity.
2.
“Checking the Status of an Activity Queue” on page 188 .
Select the activity in the activity list.
Chapter 6 Managing Process Execution 189
Monitoring and Managing Process Execution
3.
Choose Activity > Set Priority. The Set Queued Activity Priority window displays:
4.
5.
In the New prioritizing value, change the value of the queue prioritizing process attribute.
Click OK.
The activity will be placed in a new position in the activity queue, based on the new value of the queue prioritizing attribute.
190 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
Managing Timer Instances
This section describes how to check the status of a timer, reset it, or change its state.
Checking the Status of a Timer
1.
Open the Timers tab of a Process Instance property inspector, shown below.
2.
For each timer, the list displays the timer name, timer state, and expiration time.
Select a timer.
Chapter 6 Managing Process Execution 191
Monitoring and Managing Process Execution
3.
Choose Timers > Open. The Timer property inspector displays, with the basic properties of the selected timer:
Changing the Timer State and Expiration Time
➤
To change the state and expiration time of a timer
1.
Open the timer’s property inspector.
2.
through
“Checking the Status of a Timer” on page 191
.
Click the Set State button. The Set Timer window displays:
192 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
3.
4.
5.
To change the state of the timer, click one of the radio buttons in the On/Off
Control.
To change the expiration time, click one of the radio buttons in the Options box.
❍
For an elapsed timer (screen shown above), Reset sets the original elapsed time interval and Set Interval lets you enter a new elapsed time interval in
IntervalData format
(years:months:days:hours:minutes:seconds:milliseconds).
❍
For a deadline timer (screen not shown), Reset sets the deadline (expiration time) to its original value and Set Deadline lets you enter a new expiration time, in DateTimeData format (dd-nnn-yyyy hh:mm:ss, for example
03-Feb-1993 22:45:12).
Click the Set Timer button.
Managing Process Attributes
This section describes how to check the value of an attribute and its lock state and to change the attribute value or release a lock.
Checking the Value and Lock State of a Process Attribute
1.
Select the attribute in any window that contains a process attribute list:
❍ the Process Attributes tab of a Process Instance property inspector
❍ the Process Attributes tab of an Activity property inspector
Chapter 6 Managing Process Execution 193
Monitoring and Managing Process Execution
An example attribute list (the Process Attributes tab of a Process Instance property inspector) is shown below.
For each process attribute the list displays the attribute name, data type, attribute value, and lock state.
Changing a Process Attribute Value
You might change the value of a process attribute because you want to roll back an activity from ACTIVE to READY state and reoffer the activity using a different attribute-dependent assignment rule.
194 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Process Execution
➤
To change the value of a process attribute
1.
Select the attribute in any process attribute list window, as described in
“Checking the Value and Lock State of a Process Attribute” on page 193 .
2.
Choose Process Attributes > Set. The change value window displays:
3.
4.
Enter a new value.
Click the Set button.
Removing a Process Attribute Lock
You might remove a process attribute lock because you want to force a change in the value of an attribute, or because a lock was inadvertently not released during an activity rollback or abort.
➤
To remove a process attribute lock
1.
Select the attribute in any process attribute list window, as described in
“Checking the Value and Lock State of a Process Attribute” on page 193 .
2.
Choose Process Attributes > Remove Read Lock
-or-
Process Attributes > Remove Write Lock, depending on the lock state of the process attribute.
Chapter 6 Managing Process Execution 195
Monitoring and Managing Process Execution
Checking for Bottlenecks in Process Execution
Instances of a given process sometimes stall at a particular activity, causing a bottleneck in execution of that activity. This could happen, for example, if a particular activity were backlogged, or a trigger condition could not be fulfilled.
➤
To find a process bottleneck
1.
Select the engine executing the process in the iIS Console main window.
2.
The engine must be running.
Choose Monitor > Activities Resident. This opens the Activity Resident window, displaying the list of activity instances being executed by the engine.
3.
4.
For each activity instance, the list shows the activity name, activity ID, activity state, process name, and process ID.
Filter the activity list by the process name (registered process definition) of the process you are checking (see
“Filtering iIS Console Lists” on page 73
).
This filter should list activities for all active process instances corresponding to the registered process.
Look for an activity name with more than an average number of instances.
5.
You can also filter the activity list by activity name and check the number of items in the list, which is displayed in the status bar.
Filter the activity list by the name of the suspected bottleneck activity.
6.
Check the state of activities in the listing.
Depending on the situation, you might need to do further analysis. For example, if most instances of the activity are in READY state, there might currently be too few sessions to do the work or the sessions to which the activity is assigned are doing other work. If most of the activities are in PENDING state, then probably a trigger condition is not being met.
196 iPlanet Integration Server • Process System Guide • August 2001
Analyzing Process Execution
To analyze the situation further you might have to open particular activity instances, check sessions, or possibly check attributes of the corresponding process instances.
Analyzing Process Execution
The iIS product does not provide tools for analyzing information in the engine database’s history log tables that could be useful in managing and reporting on process execution. The history log provides information that can be used to answer the following types of questions:
• How long does it take for processes to complete?
You can determine how long it took for a particular process instance (identified by primary attribute) to go from start to finish, or how long it takes, on average, for process instances to complete. You can analyze this question as a function of some particular process attribute (creator, creation date, invoice value, and so forth).
• Where are the bottlenecks in process execution?
There are several approaches to finding bottlenecks. One is to determine how many process instances are currently in a given stage of completion. For example, you could create a graph of how many process instances have reached each activity, and then look at how this graph changes over time to see if a pattern emerges that indicates a bottleneck. You could also look at how this graph changes as a function of some particular process attribute.
Another approach to finding bottlenecks is to determine how long it takes, on the average, for a process instance to complete each activity. Some might take substantially longer than others. You might also look at how long the activity is in each state (PENDING, READY, ACTIVE) to determine a strategy for resolving the bottleneck.
• How well are activity queues functioning?
For a queued activity, you can see how long the queue currently is or how long it is on the average. You can determine the average length of time that activities remain in the queue, or if the prioritizing of activities in the queue leaves some activities at the bottom of the queue for an unacceptable length of time.
Chapter 6 Managing Process Execution 197
Analyzing Process Execution
• Worker productivity
You can perform productivity analyses. For example, you can tabulate how many activities have been completed in a given time as a function of the session (user). You can also look at how many activities are currently owned
(made active) by each user.
• Quality assurance
You can track the work being done on a particular process instance. For example you can determine who completed a previous step in an activity, tracking the process from one user to another.
History Log Schema
The full engine database schema is documented in the
.
“History Log Tables” on page 347 of this Appendix lists the
schema of all the history log tables. Using this information, you can write your own tools for querying the database and analyzing historical process execution data.
State Values
Many of the history log tables listed in “History Log Tables” on page 347 , have a
field that represents the state of a given engine object: process instance, activity, session, and timer. The following table shows the values corresponding to the various states of these objects:
Object
Process Instance
State
PREPARE_CREATE
CREATED
ACTIVE
COMPLETED
PREPARE_ABORT
ABORTED
Value
405
410
420
430
435
440
198 iPlanet Integration Server • Process System Guide • August 2001
Object
Activity
Timer
Session
State
PENDING
READY
PREPARE_ACTIVE
ACTIVE
PREPARE_COMPLETE
COMPLETED
PREPARE_ABORT
ABORTED
DELETED
CREATED
OFF
ON
EXPIRED
DELETED
ACTIVE
SUSPENDED
TERMINATED
Monitoring and Managing Two-Phase Commit
810
820
830
840
40
45
50
60
850
210
220
230
Value
10
20
25
30
35
Monitoring and Managing Two-Phase Commit
iIS provides a two-phase commit protocol that allows process client applications to easily synchronize iIS process state changes with application database updates.
NOTE Two-phase commit does not apply to application proxies. This section applies only to client applications that interact directly with the engine.
As illustrated in
, process client applications typically perform iIS operations that change process state maintained by the engine, while also making application database updates.
Chapter 6 Managing Process Execution 199
Monitoring and Managing Two-Phase Commit
Figure 6-3 Client Applications Change Both iIS Process State and Application Data
Client Applications iIS Process
Engine Operations iIS Process
Engine
Application
Services
Application
Transactions
Enterprise
Databases
For example, a process client application typically interacts with the engine to start an activity, performs the activity by updating application data, and then interacts with the engine again to complete the activity. If, for some reason, the update of application data fails, the CompleteActivity operation should not succeed. Or, similarly, if for some reason the CompleteActivity operation fails, the update of application data should not succeed.
The iIS two-phase commit protocol facilitates the synchronization of iIS engine operations with application transactions by letting you place iIS operations in a transactional context. As with application database transactions, the iIS two-phase commit protocol lets you split processing of iIS transactions into two phases: the first phase—preparing—guarantees that the operation (transaction) can either commit or roll back; the second phase actually performs the commit (or rollback).
NOTE “Rollback” in this usage is equivalent to “undo.” For example, rolling back a CompleteActivity operation cancels the request to complete the activity.
200 iPlanet Integration Server • Process System Guide • August 2001
Monitoring and Managing Two-Phase Commit
Because of this two-phase commit capability, an iIS engine transaction and an application transaction can be combined into a higher level distributed transaction.
The constituent transactions are placed in a PREPARE phase before either can commit. If either of the constituent transactions cannot be placed in a PREPARE phase, then the other is rolled back to its original state. In other words, the distributed transaction only commits if both constituent transactions commit, guaranteeing that application state and process state are synchronized.
The iIS two-phase commit protocol also facilitates synchronization between different activities—or sessions—in a given process instance. For example, if Client
Application A (session A) has already prepared an AbortProcess for the process instance, and Client Application B (session B) tries to complete or abort an activity belonging to that process instance, an exception is raised on session B indicating that session A is going to abort the same process instance.
The iIS two-phase commit protocol makes it possible to include the following iIS engine operations in a transactional context:
• creating a process
• aborting a process
• starting an activity
• completing an activity
• aborting an activity
When included in a transactional context, these operations are automatically placed in a PREPARE phase before being explicitly committed or rolled back. For example, any StartActivity or CompleteActivity operation would be automatically placed in a PREPARE phase.
By being placed in a transactional context, these iIS transactions can be synchronized, as described above, with application update transactions. The client application simply prepares any application (database update) operations it needs to make. If the application transaction can be successfully placed in a PREPARE phase, then the client application can commit both the application transaction and the iIS engine transaction. If the application transaction cannot be successfully placed in a PREPARE phase, then the client application should roll back the iIS engine transaction.
All iIS objects associated with a prepared transaction are unavailable for further operations until the client application explicitly commits or rolls back the transaction.
Chapter 6 Managing Process Execution 201
Monitoring and Managing Two-Phase Commit
The iIS two-phase commit protocol is implemented by placing an engine session in two-phase commit mode. iIS engine transactions for this session are automatically placed in a PREPARE phase. A session with two-phase commit enabled can only support one iIS transaction at a time.
The iIS process engine uses a unique transaction ID to monitor transactions during a two-phase transaction. The client application can specify a unique transaction ID; otherwise the engine generates a transaction ID (based on a time stamp, session name, and the session operation sequence number).
Managing Two-Phase Commit Operations
If a session should be suspended for any of a number of reasons, any iIS transaction in a PREPARE phase is retained on the session, awaiting resolution (commit or rollback). The client application is normally responsible for resolving these transactions; however, in the case of failure, these transactions may be left permanently in the PREPARE phase. Because of this, it is up to a system manager to check for and resolve any transactions left in a PREPARE phase.
For example, a client application may perform an activity, but fail before it can notify the engine to commit the CompleteActivity operation. Similarly, the engine could fail before receiving the commit. Both these situations result in inconsistency of state information between the client application and engine.
To properly resolve iIS transactions in a PREPARE phase, however, you must investigate whether related application transactions were committed or aborted.
How you do this depends on the details of the application and how it keeps track of transaction IDs.
You can use Conductor Script commands to identify and resolve transactions in a
PREPARE phase, as described in
“Monitoring and Managing Two-Phase Commit
.
202 iPlanet Integration Server • Process System Guide • August 2001
Chapter 7
Troubleshooting
This chapter discusses a number of topics and approaches related to diagnosing problems in your iIS process management system.
This chapter covers the following kinds of troubleshooting information:
• alarms
• exceptions
• messages
• performance indicators
Introduction
iIS provides a number of tools to help you diagnose engine problems or problems in process execution with your iIS enterprise applications:
• the Process Engine Alarms window
• the engine component log files
• the iIS Console Trace window
• the Engine Event Trace window
• the iIS Console performance charts
These tools all display various types of information that can be useful in uncovering and diagnosing the cause of problems.
203
Introduction
The information displayed in these iIS tools falls into the following categories:
Alarms A number of error conditions in the functioning of an iIS process engine that might require your intervention are reported as alarms. These conditions range from a communication problem between engine components to exceptions generated in the primary engine unit in the course of process execution. Alarms are displayed in the Process Engine Alarm window (see
Window” on page 205 ) and written to an alarms table in the engine’s history log
database (see
Exceptions All error conditions detected by an engine (including alarms) cause an exception to be raised. When the task that encounters the condition originates in the client, the error is reported directly to the client (for example, attempting to start an activity that has already been started). When an error is detected by an internal engine task (for example, attempting to start an unregistered subprocess), the engine records a process exception, activity exception, session exception, or timer exception in the primary engine unit’s log file (see
“Using the iIS Console Trace Window” on page 215
).
Messages Each engine component—whether it be an engine unit, database service, or governor—can generate many types and levels of messages. You can specify the type and level of messages you want to have logged to a component’s
problems.
Performance Indicators You can monitor various aspects of process execution using the iIS Console. For example, you can monitor sessions and executing processes as described in
Chapter 6, “Managing Process Execution.” You can also
monitor a number of specific performance indicators using the charting capabilities described in
“Performance Charts” on page 221 .
This chapter describes how to use the iIS alarms window, log files, tracing window, and performance window to display the above categories of troubleshooting information.
204 iPlanet Integration Server • Process System Guide • August 2001
Process Engine Alarms Window
Process Engine Alarms Window
A number of engine conditions result in an alarm. An alarm is a message notifying you of a condition in the functioning of an iIS process engine that might require intervention.
The following list shows these alarms and a description of the condition that gives rise to each:
Alarm
ChannelDisconnect
DatabaseDisconnect
EngineUnitForceStandby Because an engine unit cannot operate independently in a fault tolerant state, the engine unit has been forced into
STANDBY state due to an interruption of contact with its partner.
EngineUnitOnline The engine unit has gone into ONLINE state and is now capable of accepting client connections.
EngineUnitShutdown
Description
A communication channel to the engine unit has been disconnected due to the failure of a component or an interruption of the network.
A database service has been disconnected due to the partition shutting down or a network failure.
Exception
GovernorDisconnect
An engine unit has shut down and is no longer running as a partition, due either to operator intervention or to a failure in the software. If a software failure is suspected, look in the log files for the engine units and governor.
An exception has been generated in the engine unit. The
Severity and Message fields contain the information about the exception.
A communication channel between an engine unit and the
Governor has been disconnected due to the failure of a component or an interruption of the network.
ProcessAbort
StartupFailure
UserAccess
A process has been aborted. The details field of this alarm gives the ID of the process that was aborted. If this alarm is unexpected, look in the log files for further information.
An engine unit has failed to start up correctly. Further information as to the reason for the failure can be found in the governor log file. The engine unit is now in STANDBY state.
Access to something has been denied to a user. The Reason field gives the reason for the access violation.
Chapter 7 Troubleshooting 205
Process Engine Alarms Window
Monitoring Alarms
Alarms for any number of engines can be displayed in the Process Engine Alarms window, allowing you to monitor all your iIS process engines from one central location. (Alarms can also be written to the engine database of any engine for which history logging is turned on.)
To view alarms for a specific engine, you must first register the engine with the alarm service. An engine can be registered with the alarm service before it is started up, and can be unregistered as well.
➤
To register an engine with the alarm service
1.
Choose Environment > Alarms in the iIS Console main window. The Select an
Engine window displays:
2.
Select an engine and click OK.
The engine does not have to be running to register it with the Alarm service.
206 iPlanet Integration Server • Process System Guide • August 2001
Process Engine Alarms Window
3.
The Process Engine Alarms window displays.
In the following illustration, a registered engine, ceengine, was shut down, causing the EngineUnitShutdown alarm to be displayed.
➤
To unregister an engine from the Alarm service
1.
Select an engine in the engine list in the right hand panel of the Process Engine
Alarms window.
2.
Choose Engines > Remove Engine.
You can filter the alarms that are displayed in the Process Engine Alarms window, and also search for alarms in the window.
➤
To filter alarms in the Process Engine Alarms window
1.
Choose Alarms > Filter.
2.
The Filter Expression window opens. This window allows you to build an expression to use for filtering the display. Expressions are built using the available attributes listed in the window.
In the Filter Expression window, drag an attribute from the Available
Attributes list to the Filter Expression editing area.
3.
Using a boolean operator together with a legal value for the attribute, build the filter expression, and then click OK.
Attribute values must be legal for the type of the attribute. String values must be enclosed in quotes.
Chapter 7 Troubleshooting 207
Process Engine Alarms Window
You can add additional expressions to build complex filters. For example, the following expressions displays alarms of type EngineUnitShutdownAlarm for the engine named ceengine:
Type="EngineUnitShutdownAlarm"
Engine="ceengine"
For more information on creating filter expressions, refer to
.
➤
To search for an alarm in the Process Engine Alarms window
1.
Choose Alarms > Find.
2.
3.
4.
The Filter Expression window opens.
In the Filter Expression window, build an expression for the alarms you are trying to find.
Use the steps outlined in the previous procedure to build the expression.
Click OK.
To search again, using the same expression, choose Alarms > Find Again.
Viewing Alarms
After an engine has been registered with the Alarm service, any alarms sent by that engine (either in start-up or while it is running) are displayed in the Process Engine
Alarms window. The Process Engine Alarms window must be open. Alarms that occur when the Process Engine Alarms window is not open, cannot be displayed by opening the window. To see the alarm in that case, you have to open the engine unit log file (see
“Engine Log Files” on page 210 ).
208 iPlanet Integration Server • Process System Guide • August 2001
Process Engine Alarms Window
➤
To get detailed information about an alarm
1.
Select the alarm in the Process Engine Alarms window.
2.
Right-click and choose Alarm > Open from the popup menu. The Alarm
Details window displays:
➤ To remove an alarm from the Alarm window
1.
Select the alarm in the Alarms window.
2.
Right-click and choose Alarm > Remove from the popup menu.
Chapter 7 Troubleshooting 209
Engine Log Files
Engine Log Files
Each iIS process engine component, like other iPlanet UDS partitions, writes to a log file that records exceptions and message output. The component log files are therefore an important source of troubleshooting information.
The log file for each component is written in the FORTE_ROOT/log directory of the node on which the component is executing. Log files are named according to the executing partition’s name. Engine components can be executed as standard partitions interpreted by an iPlanet UDS ftexec partition or as compiled partitions.
The corresponding log file names and locations on the host server node are as follows: iPlanet UDS Partition
Standard partition
Compiled partition
Standard Output Log File in FORTE_ROOT/log/ forte_ex_process_ID.log (for example, forte_ex_13456.log)
filename_process_ID.log
Several kinds of information are written to an engine component log file. Some kinds are written automatically and some are under your control. Some information is generated by the underlying iPlanet UDS runtime system, while other information is specific to the execution of iIS processes. In general the information falls into four categories: engine exceptions, requested message output, instrument data, and audit traces.
Engine Exceptions All iIS error conditions detected by an engine cause an appropriate exception to be raised. When the error is detected by an internal engine task (for example, attempting to start an unregistered subprocess), the engine records the exception in the primary engine unit’s log file. (It also writes it to the iIS
Console trace window, if open.)
Requested Message Output You can request that specific categories of messages be logged to any iIS engine component log file (see
level of messages you want to have logged. (These messages are also written to the iIS Console trace window, if open.)
210 iPlanet Integration Server • Process System Guide • August 2001
Engine Log Files
Instrument Data You can decide to have instrument data—such as application resource usage or performance statistics—collected by the underlying system for an engine component and written to the partition log file at time intervals you can specify. The logging of instrument data is determined by values you set for special logging instruments using iPlanet UDS system management tools, such as the iPlanet UDS Environment Console.
Audit Traces Audit traces for important system events (such as starting and stopping partitions, and so forth) are automatically written to log files, depending on the event. You cannot turn off the logging of this information.
Once a component has come on line, you can view its log file from within iIS
Console.
➤
To view an engine component log file
1.
Select an engine from the list of running engines in the iIS Console main window.
2.
Choose Engine > Status. The Engine Status window displays.
3.
Select the engine unit for which you want to see the log file.
Chapter 7 Troubleshooting 211
iIS Console Trace Window
4.
Click the View Partition Log button.
NOTE If an engine component has not come online, its log file cannot be viewed from iIS Console. In that case you need to access the log file directly on the component’s host node.
iIS Console Trace Window
iIS Console provides a trace window that displays information written to iIS engine component log files. This information consists of output logged by engine components when they encounter exceptions (error conditions), as well as messages generated in process execution.
Messages and Message Filters
iIS engine components—engine units, database services, and the governor— generate many types and levels of messages. These messages are generated in the course of execution and can be used, in addition to exception output, for tracking down problems.
To view these messages you must specifically request the type and level of message you want to see, and for which engine component. The specified messages are then written to the corresponding component log files (and to the iIS Console
Trace window).
You can specify message filters in a number of ways:
• You can set an environment variable (FORTE_LOGGER_SETUP) on each node that specifies the message filters for every iPlanet UDS partition (engine component) started on that node.
• You can set message filters for an individual iPlanet UDS partition (overriding the environment variable—or its default value) by specifying a log flag (-fl) on the partition start-up command. (There is currently no way to do this in iIS
Console or Conductor Script.)
• You can set message filters dynamically for a running partition (overriding the specification in a logger flag or environment variable) by using the File >
Modify Log Flags command in the trace window of the iIS Console (or the
Conductor Script ModLogFlags command,
212 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Trace Window
This section discusses how to use the iIS Console Trace window to select and display messages generated by iIS engine components.
Specifying Message Filters
The syntax for specifying log message filters is shown in
specify a standard output log file, “%stdout,” as the log file name (see “Engine Log
Files” on page 210 ). You can specify more than one log file if you want different
information written to different files. For each file you can specify any number of filters, each separated by a space.
Figure 7-1 Specifying iPlanet UDS Message Output Filters
FORTE_LOGGER_SETUP (or -fl flag):
“file_name (message_type [:service_type[:group_number[:level_number]]])...”
Message Types err Error messages sec Security messages aud Audit messages prf Performance information cfg Configuration modification trc Debugging information
* all of the above
In general, for each log file you can specify four levels of filter, as follows:
Message type (mandatory) You can include more than one message type separated by spaces—the message types available are shown above.
Service type Each message type can be divided into a maximum of ten service types, which typically map to important application services.
Group number Each service type can be divided in turn into a maximum of 63 group numbers, which typically map to a group of facilities.
Level number Each group number can be subdivided into up to 255 additional levels.
Chapter 7 Troubleshooting 213
iIS Console Trace Window
Group
3
4
1
2
5
iIS Message Filters
iIS message filters follow the general guidelines above and have the following particularities:
Message type trc (debug)
Service type cr (iIS runtime)
Group number iIS uses the following group designations:
Description
Engine
Session
Process
Activity
Timer
7 History
8 Access checking
9
10
13
Recovery
Registration
Client application messages
Level number iIS uses the following level designations:
Group
2
3
4
255
Description
Coarse
Medium
Fine
Method entry and exit (where implemented)
214 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Trace Window
For example, an iIS message filter for a primary engine unit might be as follows:
FORTE_LOGGER_SETUP: "%stdout(trc:cr:2:2)"
This filter specifies that all messages about sessions created in the engine —but not a lot of detail—be written to the primary engine unit’s log file (on the server node on which the primary engine unit is running) and to the iIS Console trace window
(if you have opened it at least once before).
If you do not specify any iIS message filters, none are set by default.
Using the iIS Console Trace Window
You can use the iIS Console trace window to select and display messages generated by iIS process engine components and to view exception output. Using the trace window, you can monitor engines distributed throughout your environment from one central location.
➤
To open the iIS Console Trace window
1.
Select a running engine in the iIS Console main window.
2.
Choose Engine > Trace. This opens the iIS Console Trace window
The trace window shows all messages you specify for components of the selected engine.
Setting Message Filters
The iIS Console provides a Modify Log Flags window for setting the message
filters described in the previous section, “iIS Message Filters.”
Chapter 7 Troubleshooting 215
iIS Console Trace Window
➤
To set message filters for a selected engine
1.
Select a running engine in the iIS Console main window.
2.
Choose Engine > Trace. The iIS Console Trace window displays.
3.
Choose File > Modify Log Flags. This opens the Select Component window.
4.
Select an engine component and click OK to open the Modify Log Flags window.
5.
Add, modify, or delete a message filter and click OK.
Use the message filter specifications documented in the previous section,
NOTE To specify the trc message type, select Debug in the Message column of the Modify Log Flags dialog.
216 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Engine Event Filter Window
All messages generated by the component that meet the specification are now written to the trace window, as well as to the components log file.
Special Example: Write Client Messages to Trace Window
As an example of using message filters, suppose you want to have all messages generated by client applications written to the iIS Console trace window. To do this, the client applications must generate the messages and pass them to the engine to be written to the engine log file and trace window. To pass the messages to the engine, the client partitions must also set their trace flag to the value shown in the procedure below. (This is a special procedure used for troubleshooting and diagnosing client application problems.)
➤
To set the engine tracing
1.
Select the engine in the iIS Console main window.
2.
Choose Engine > Trace. The iIS Console Trace window displays.
3.
4.
5.
Choose File > Modify Log Flags.
In the Modify Log Flags window, enter the following filter: Debug:CR:13:4
This filter causes all messages generated by client applications that have this same trace flag set to be written to the engine trace window and the primary engine unit log file.
For each client partition whose messages you want to trace in iIS Console, set the following filter: Debug:CR:13:4
iIS Console Engine Event Filter Window
iIS Console provides a filtering mechanism and trace window to let you view information about iIS process engine events. These messages are generated in the course of process execution and can be used, in addition to exception output, for tracking down problems.
When you trace engine events for a specified engine you can:
• view all engine events for that engine
• view all engine events belonging to an existing process instance
• view all engine events belonging to the next process instance of a specified process definition
• view engine events according to a custom filter you specify
Chapter 7 Troubleshooting 217
iIS Console Engine Event Filter Window
Engine Event Types
iIS Console engine event types consist of:
• timer state changes (on/off/value change)
• session events (start, suspend, terminate)
• activity state changes
• process events (start, terminate, new registration, deregistration)
• security events (access denial for invalid logon)
• engine state changes (start, standby, shutdown)
Using the iIS Console Engine Event Filter
Window
You can use the iIS Console engine event filter window to specify and display messages regarding engine event generated by any iIS process engine in your environment.
➤ To open the Engine Event Filter window
1.
Select a running engine in the iIS Console main window.
2.
Choose Engine > Event Trace. This opens the Engine Event Filter window.
218 iPlanet Integration Server • Process System Guide • August 2001
iIS Console Engine Event Filter Window
Displaying All Engine Events
You can view all engine events for a running engine.
➤
To view all engine events for the selected engine
1.
From the Engine Event Filter window, select the option Show all engine events.
Each engine event is identified by event type, class, ID, description, and time of occurrence. The information starts displaying after the next engine event occurs.
Displaying Process Instance Events
You can display all engine events for a given process instance, either one that exists, or the next process instance for a given process definition in your repository.
➤
To view all engine events for an existing process
1.
From the Engine Event Filter window, select the option Existing process instance: and enter the ID for that process instance.
Chapter 7 Troubleshooting 219
iIS Console Engine Event Filter Window
Events for the specified process instance display:
➤
To view all engine events for the next process instance of a specific process definition
1.
From the Engine Event Filter window, select the option Next process instance of: and select a process definition from the drop down list.
All engine events for the next process instance of the process definition will start displaying when the process instance starts. Each engine event is identified by event type, class, ID, description, and time of occurrence.
220 iPlanet Integration Server • Process System Guide • August 2001
Performance Charts
Filtering Engine Events
A fourth way to view engine events is by providing a custom filter. You can filter on events involving sessions, process instances, activities, engine objects, timers
and registrations. For details on valid filter expressions, see “CreateFilter” on page 279 .
➤
To specify a custom filter
1.
Select the option Custom filter and enter a valid filter expression.
Events which satisfy the filter expression are displayed:
Performance Charts
An iIS process engine that is performing process execution without any visible sign of problems might nevertheless encounter performance bottlenecks. One cause might be increased load on the engine.
Chapter 7 Troubleshooting 221
Performance Charts
It is therefore a good idea to regularly monitor a number of performance indicators—instrumentation within an engine that can be displayed over time in the iIS Console Performance Charts. The instruments displayed in the Performance
Charts are the following:
Instrument
Process Instances
Activities
Average response time
Average transaction commit time
Allocated memory
Peak allocated memory
Description number of active process instances number of activities in the ready or active state the average time it takes for the engine to complete a request made by a session (such as OpenSession, StartActivity, and
CompleteActivity) the time it takes the engine to commit a change of state (complete a transaction involving the engine database) the amount of the active memory currently allocated to objects created by the primary engine unit the amount of allocated memory remaining after the most recent memory reclamation (probably the best measure of active memory utilization)
These instruments indicate how performance might be impacted by an increasing load on the engine.
For example, as the number of sessions increases over time, you would expect the average response time to increase. At some point, you might decide to add an additional engine to your workflow system to help balance the load.
As the number of process instances and activities increase over time, you would expect the average transaction commit time to increase. In this case you might decide to start up additional database services to speed throughput to the engine database.
In many situations these factors have complicated interactions and you have to monitor these indicators carefully under varying conditions, analyzing the source of any performance bottlenecks.
Viewing Performance Indicators
You can view performance indicators for any running engine in the Performance window.
222 iPlanet Integration Server • Process System Guide • August 2001
Performance Charts
➤
To view performance indicators for an engine
1.
Select a running engine in the iIS Console main window.
2.
Choose Monitor > Performance.
3.
The Performance Charts window is displayed. You can choose View >
Observed Values to expand the Charts window to display maximum, last observed, and minimum values for the charts.
You can change the interval between each update to the chart by changing the
Update Every ___ seconds field. You can also change the number of entries recorded on the chart by changing the Record ___ Observations field.
Chapter 7 Troubleshooting 223
Performance Charts
4.
To set the vertical scale parameters for the chart and see the maximum and minimum values recorded by this chart, click somewhere in the chart, then right-click and choose Chart > Properties from the popup menu.
The Timeline Properties window displays. You can choose to display observed values or the differences between succeeding values.
5.
To modify the appearance of the chart, click somewhere in the chart, then right-click and choose one of the following commands from the popup menu:
❍
Chart > Line Color
❍
❍
Chart > Line Weight
Chart > Set Default
224 iPlanet Integration Server • Process System Guide • August 2001
Performance Charts
Logging Performance Information
You can save performance information to a log file.
➤
To log performance information
1.
At the Performance Charts window, choose File > Set Logging File.
2.
3.
4.
Define a name and location for the performance log data file.
Click OK.
Choose File > Start Logging to File.
➤
To stop logging performance information
At the Performance Charts window, choose File > Stop Logging to File.
Chapter 7 Troubleshooting 225
Performance Charts
226 iPlanet Integration Server • Process System Guide • August 2001
Chapter 8
Using the Conductor Script Utility
This chapter describes the Conductor Script utility, the iIS command line system management interface.
The Conductor Script utility is the command line equivalent of the iIS Console.
However, Conductor Script also lets you incorporate system management tasks into scripts. These scripts can then be executed at engine startup, regular intervals, or other times to register iIS distributions, or to start and shut down engine components.
This chapter covers the following topics:
• starting and exiting Conductor Script
• working with Conductor Script
• using Conductor Script to perform system management tasks
For a complete reference listing of all Conductor Script commands, see
Appendix A, “Conductor Script Commands.”
Overview
With the exception of configuring iIS process engines, the Conductor Script utility is the functional equivalent of the iIS Console: you can use it to perform iIS process management tasks, such as managing iIS engines, managing registration, and managing process execution.
Like the iIS Console, Conductor Script connects to and communicates with the executing Environment Manager and any active Node Managers in your environment. It lets you perform iIS process management tasks by providing you with access to your iIS engines and to the full hierarchy of iPlanet UDS system management agents.
227
Starting Conductor Script
Unlike the iIS Console, however, you can use Conductor Script to perform system management by building and executing predefined scripts of Conductor Script commands. For information on building and executing Conductor Script scripts,
see “Writing and Executing Scripts” on page 232
.
This chapter explains how to perform system management tasks using Conductor
Script. It provides a list of Conductor Script commands for various sets of tasks, and in some cases provides detailed step by step procedures. However, it does not provide background and conceptual information offered elsewhere in this manual.
For a complete reference listing of all Conductor Script commands, refer to
Appendix A, “Conductor Script Commands.”
Conductor Script Help
Conductor Script provides an online help utility, which provides help for all
Conductor Script commands. At a Cscript prompt type Help to list all the available commands. For help on a specific command, type Help plus the command. You can also use wildcard characters to get help on groups of commands.
NOTE Some commands are associated with a particular engine component, so help for those commands is only available when an engine or the particular component is current.
For information on the Help command, see “General Conductor Script Operations” on page 231 .
Starting Conductor Script
You can start Conductor Script on any node in your iPlanet UDS environment where it has been installed.
➤
To start Conductor Script on Windows or Windows NT
1.
Double-click the Conductor Script icon.
2.
Enter a valid password if one is requested (see “SetPassword” on page 300 ).
228 iPlanet Integration Server • Process System Guide • August 2001
Starting Conductor Script
➤
To start Conductor Script on UNIX, OpenVMS, or Windows NT
1.
Use the cscript command (see
“Using the Cscript Command” below for
information).
2.
Enter a valid password if one is requested (see “SetPassword” on page 300 ).
When Conductor Script starts, it opens a cscript command prompt.
Using the Cscript Command
As mentioned above, you can start iIS Console on command line-based operating systems by executing the cscript
command.
The syntax of the cscript command for most platforms: cscript [-fl message_filters][-fm memory_options] [-i input_file]
[-o output_file] [-fns name_service_address]
The syntax of the cscript
command for OpenVMS:
VFORTE CSCRIPT
[/LOGGER=message_filters]
[/MEMORY=memory_options]
[/INPUT=input_file]
[/OUTPUT=output_file]
[/NAMESERVER=name_service_address]
As in all iPlanet UDS command line specifications, if you use a name that includes a space, you should enclose the name in double quotation marks.
The following table describes the command line flags for the cscript
command.
Flag
-fl message_filters
/LOGGER=message_filters
Description
Specifies the log flags to use for the Conductor
Script session. See the iPlanet UDS System
Management Guide for information about the syntax for specifying log flags. Overrides the
FORTE_LOGGER_SETUP environment variable setting. On UNIX, you must specify the log flags in double quotes.
Chapter 8 Using the Conductor Script Utility 229
Working with Conductor Script
Flag
-fm memory_options
/MEMORY=
memory_options
-i input_file
/INPUT=input_file
-o output_file
/OUTPUT= output_file
-fns name_service_address
/NAMESERVER=
name_service_address
Description
Specifies the memory flags to use for the
Conductor Script session. See the iPlanet UDS
System Management Guide for syntax information.
Overrides defaults appropriate for the operating system. On UNIX, you must specify the memory flags in double quotes.
Specifies an input file. The file should consist of a
Conductor Script script—a set of Conductor
Script commands—that you want to execute automatically when the Conductor Script utility starts.
Specifies an alternate output file, in addition to stdout.
Specifies the name service address for the environment in which this application will run.
This value overrides the value, if any, specified by the FORTE_NS_ADDRESS environment variable.
If you want your application to be able to switch to a backup Environment Manager if the primary
Environment Manager fails, you can also specify multiple name service addresses, as discussed in the iPlanet UDS System Management Guide.
Working with Conductor Script
Conductor Script is a command line utility built on top of the iPlanet UDS Fscript command utility. As such, it includes Fscript commands for performing repository-based operations, as well as a large number of iIS-specific commands.
(A few Fscript commands, however, have been disabled in Conductor Script.)
This section covers topics related to some of the general purpose Fscript commands accessible from within Conductor Script. iIS-specific operations and commands are discussed in subsequent sections. The topics covered in this section are the following:
• general Conductor Script operations
• writing and executing scripts
• operating system and file management commands
230 iPlanet Integration Server • Process System Guide • August 2001
Working with Conductor Script
For full reference documentation of the commands discussed below, consult the
Fscript Reference Guide.
General Conductor Script Operations
The following table lists Conductor Script commands used for general operations such as getting online help, defining the format of file names, specifying a directory search path, and so on:
Command
AddAlias
AddPath
Exit
Help
ModLogger
Quit
RemoveAlias
SetOutFile
SetPath
ShowAlias
ShowPath
Arguments alias_name command_string directory_name
[;directory_name…]
——
[comand_name| match_string]
+(log_flags)|
–(log_flags)
——
[alias_name]
[file_name] directory_name
[;directory_name…]
[alias_name]
——
Function
Define an alias for a Conductor Script command and its arguments.
Add the specified directories to the current search path (see SetPath).
Exit Conductor Script.
List help for general Conductor Script commands and currently available
FNscript commands. Use a wildcard (*) to get help on similarly named commands.
Modify the current iPlanet UDS log message filters (log flag settings) for
Conductor Script.
Exit Conductor Script.
Remove an alias definition.
Specify a file where standard output is printed.
Set the directory search path used by any of the commands that take a file name as an argument.
Display one or all defined aliases with their expansions.
Show the current directory search path
(see SetPath).
Chapter 8 Using the Conductor Script Utility 231
Working with Conductor Script
Command
UseLocal
Arguments
——
UsePortable ——
Function
Set Conductor Script to recognize file names specified in local operating system format.
Set Conductor Script to recognize file names specified in iPlanet UDS portable name format.
Writing and Executing Scripts
This section describes Conductor Script commands you use to write and execute scripts to automate iIS process management tasks. For full reference documentation of the commands, consult the Fscript Reference Guide.
One of the advantages of using Conductor Script over the iIS Console is that
Conductor Script lets you automate your routine system management tasks. You can capture a sequence of Conductor Script operations into a script file and then run that file at a later time.
You can run a script either by starting Conductor Script with the -i flag (and supplying the script file name) or by starting Conductor Script and then issuing the
Include command when you want to run the script.
Comments
To include comments in your scripts, start the line containing the comment with the # character, as shown in the following example:
# Shut down the Banking engine.
FindEngine Banking
Shutdown
232 iPlanet Integration Server • Process System Guide • August 2001
Working with Conductor Script
The following table lists Conductor Script commands most often used for writing and executing scripts:
Command Arguments Function
CommentOff
CommentOn
——
——
Stop writing script file commands and output to standard output.
Write script file commands and output to standard output.
Delay milliseconds Delay execution of the next command for the specified number of milliseconds.
Include
Repeat
Script
ShowExpansions filename Execute the commands in a specified script file.
repeat_count Repeat execution of the next command the specified number of times.
filename show_flag
Capture Conductor Script commands and write them into a specified script file.
Enable or disable the printing of alias expansions to standard output when they occur.
SilentOff
SilentOn
Step
——
——
——
Turn off printing of exceptions to standard output.
Turn on printing of exceptions to standard output.
Step through the commands in an include script, prompting you for each command.
Operating System and File Management
Commands
The following table lists Conductor Script commands for interacting with the operating system on a node to perform file management operations.
Command
Cd
Chmod
Arguments Function directory_name Change the current working directory.
mode
file_name [r]
Change the access permissions of the specified file.
Chapter 8 Using the Conductor Script Utility 233
Working with Conductor Script
Command
CopyFile
Cp
Directory
Duplicate
ExecCmd
Arguments file1_name
file2_name [r]
Function
Copy a specified file in the local file system.
file1_name
file2_name [r] opsys_cmd
[bg_flag]
[in_file]
[out_file]
[err_file]
Copy a specified file in the local file system.
directory_name List the files in a directory.
file1_name
file2_name [r]
Copy a specified file in the local file system.
Execute the specified operating system command.
ExecLocal opsys_cmd Execute the specified operating system command (for path names in opsys_cmd that use local format).
ExecPortable
ListFile
ListFiles opsys_cmd Execute the specified operating system command (for path names in opsys_cmd that use portable format)
ListFile Lists the contents of the specified file onto standard output.
directory_name List the files in a directory.
Ls
MkDir
Mv directory_name List the files in a directory.
directory_name Make a new directory.
old_file_name new_file_name
Rename a specified file in the local file system.
Pwd
ReadIntoFile
Rm
SetDefault
WhichFile
—— file_name
[term_str] file_name
Display the name of the current working directory.
Read subsequent lines and write them to the specified file until the terminating string is encountered.
Remove a specified file in the local file system.
directory_name Change the current working directory.
file_name Find the specified file in the current directory search path.
234 iPlanet Integration Server • Process System Guide • August 2001
Managing iIS Process Engines with Conductor Script
Managing iIS Process Engines with
Conductor Script
This section describes how to perform the following engine management functions using Conductor Script:
• starting an engine
• monitoring an engine
• changing engine component states (including stopping an engine)
Conductor Script cannot be used to configure an engine. You can use iIS Console
(see
“Configuring an Engine” on page 85 ) or edit an engine configuration file by
hand (using the information in “Engine Configuration File” on page 90 ).
For background information on starting an engine, monitoring it, and changing component states, as well as how to perform these functions using iIS Console, see
Chapter 4, “Managing Engines.”
Starting an Engine
You can start engine components from a centralized location using the Conductor
Script utility (see Appendix A, “Conductor Script Commands” ). Conductor Script
uses iPlanet UDS system management agents to start the partitions corresponding to each of the engine components, as specified in the engine configuration file.
➤
To start an engine
1.
Enter
ListEngines
to get a list of configured engines.
2.
3.
The list indicates which engines are online.
Use the
FindEngine
command to choose the engine you want to start.
The selected engine is the current engine.
Use the
StartEngine
command to start the current engine.
The engine starts using the component partitioning and startup information in
the engine configuration file (see “Engine Configuration File” on page 90 ). The
components are started in the following order: governor, engine units, database services.
Chapter 8 Using the Conductor Script Utility 235
Managing iIS Process Engines with Conductor Script
Starting Individual Engine Components
You can start an individual engine component on any node on which it is installed.
Each component is an application consisting of a single server partition that must establish communication channels with other components.
Except for the governor, as each of these partitions is started, it must be provided a component name and the name of the engine to which it belongs. The partition uses this engine name along with its component name to explicitly register itself with the iPlanet UDS Name Service. As each component starts up, it looks in the
Name Service registry for the names of other components with which it must establish a communication channel. When all necessary communication channels are established, the primary engine unit can log on to its database and perform other operations needed to come fully online.
The engine startup protocol is designed to allow components to start in any order.
They simply wait for the other components to which they must connect. However, because an engine unit will eventually time out if it cannot log on to its database or establish a communication channel with its partner or the governor, there is a preferred order for engine startup if there might be a delay in starting a component.
➤
To start an engine where delays might be involved
1.
Start the governor.
2.
3.
Start at least one database service.
Start each engine unit.
➤ To start an individual engine component (governor, database service, or engine unit)
1.
Use the FindEngine command to the engine you want to start to the current engine.
2.
Use the
FindNode
command to set node for the component to the current node.
3.
Use the appropriate Conductor Script Start command to start the engine component on the current node.
236 iPlanet Integration Server • Process System Guide • August 2001
Managing iIS Process Engines with Conductor Script
The Conductor Script commands used to start engines are documented in
Appendix A, “Conductor Script Commands” and summarized in the following
table:
Command
ListEngines
FindEngine
StartEngine
FindNode
StartGovernor
StartDBService
StartUnit
Arguments
—— engine_name
[newLog]
[newState]
[newRegistration]
[cold] node_name
—— service_name priority unit_name
[cold]
Function
Display a list of all running and configured iIS process engines in the environment.
Set specified engine as the
“current” engine. The engine (nor any of its components) does not have to be running.
Start all components of the engine as specified in the engine configuration file.
(Includes various start options that create new engine database tables.)
Set the specified node as the
“current” node. The node must exist in the environment.
Start the governor for the current engine on the current node.
Start the specified database service for the current engine on the current node.
Start the specified engine unit for the current engine on the current node.
(Includes cold start option to create engine database.)
See…
Chapter 8 Using the Conductor Script Utility 237
Managing iIS Process Engines with Conductor Script
As indicated in the table, the engine unit partition has a startup argument which specifies that when the engine unit comes ONLINE, that it create the required tables in the engine database. This argument should be used when you start an engine for the first time, or if you explicitly want to delete the existing database schema.
NOTE A cold start purges and deletes any tables that already exist, including the registration table and the current state and history log tables. Be careful when using this option, since you can lose unrecoverable information.
Example Manual Startup Scenario
You can override the component partitioning scheme in the engine configuration file by starting each engine component manually. As an example, take the engine partitioning scheme illustrated in
Figure 4-2 on page 88 . Assume the iPlanet UDS
environment is named “Galaxy”, and the engine is named “Enterprise.” The partitioning scheme is summarized in the following table:
Component
Governor
Primary engine unit
Backup engine unit
Database service
Database service
Database service
Database service
Database service
Component Name primero secundo main1 (priority=10) main2 (priority=10) main3 (priority=10) load1 (priority=9) load2 (priority=8)
Location (Node Name)
Server1
Server2
Server3
Server4
Server4
Server4
Server1
Server3
238 iPlanet Integration Server • Process System Guide • August 2001
Managing iIS Process Engines with Conductor Script
The following Conductor Script commands start up the Enterprise engine in the preferred order.
findengine galaxy.enterprise
findnode server1 startgovernor startdbservice load1 9 findnode server2 startunit primero findnode server3 startunit secundo startdbservice load2 8 findnode server4
Monitoring Engines and Engine Components
After you have started an engine, you should ensure that it has started successfully and monitor it periodically.
You can get status information about the engine as a whole and about each of the individual engine components. Conductor Script uses iIS engine agents to gather engine component data. Each agent has a set of instruments that report relevant information.
Monitoring the Engine
Typically you want to know which engine components are up and running.
➤
To check the engine runtime configuration
1.
Use the
ListEngines
command to see which engines are running in your environment.
2.
3.
Use the FindEngine command to make the engine of interest current.
Use the
ShowStatus
command to display the runtime configuration of the current engine.
Chapter 8 Using the Conductor Script Utility 239
Managing iIS Process Engines with Conductor Script
The Conductor Script commands used to monitor engines are documented in
Appendix A, “Conductor Script Commands” and summarized in the following
table:
Command Arguments Function See…
FindEngine
ShowStatus engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
[short]
ListEngines
ShowEngine
—— Display a list of all running and configured iIS process engines in the environment.
engine_name Display status of the specified engine.
Display status of the current engine.
(No engine components need be running for this command to work.)
Monitoring Individual Engine Components
You can get more information about individual engine components.
➤
To monitor individual engine components
1.
Use the
ListEngines
command to see which engines are running in your environment.
2.
3.
4.
Use the FindEngine command to make a particular engine current.
Use the appropriate
FindComponent
command to make a component current.
Use the ShowStatus command to display information about the current component.
240 iPlanet Integration Server • Process System Guide • August 2001
Managing iIS Process Engines with Conductor Script
The Conductor Script commands used to monitor individual engine components are documented in
Appendix A, “Conductor Script Commands” and summarized
in the following table:
Command Arguments Function
FindEngine engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
FindDBService service_name Set the specified database service for the current engine as the current component. The database service must be running.
FindGovernor
FindPrimary
FindUnit
ListEngines
ShowStatus
——
—— unit_name
——
[short]
Set the governor for the current engine as the current component.
The governor must be running.
Set the primary engine unit for the current engine as the current component. The primary unit must be ONLINE.
Set the specified engine unit for the current engine as the current component. The engine unit must be running.
Display a list of all running and configured iIS process engines in the environment.
Display the status of the current component. If the current component is an engine unit in the
ONLINE state, then this command shows the full instrumentation implemented for all the engine’s internal manager objects.
See…
Chapter 8 Using the Conductor Script Utility 241
Managing iIS Process Engines with Conductor Script
Changing Engine States
You can change the state of an engine by changing the state of an engine unit or by shutting down an engine component.
Changing Engine Unit States
You might want to change the state of an engine unit for a number of reasons. For example, you might want to close all client sessions with a primary engine unit
(change its state from ONLINE to STANDBY) in order to perform administrative functions on the database. Or you might want to place a primary engine unit in
STANDBY state so you can make its partner primary. When the partner goes from
STANDBY to ONLINE, it recovers state information from the database.
➤
To change the state of an engine unit
1.
Use the
FindEngine
command to make the engine of interest current.
2.
3.
Use the FindUnit or FindPrimary command to make the component of interest current.
Use the
SetState
command to set the engine unit state.
If you want to place the primary unit on standby, and the backup unit online, you can perform this operation in a single command using the SetPrimary command.
The Conductor Script commands used to change engine states are documented in
Appendix A, “Conductor Script Commands” and summarized in the following
table:
Command Arguments Function
FindEngine
FindUnit
FindPrimary
SetState engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
unit_name
—— state
Set the specified engine unit for the current engine as the current component.
The engine unit must be running.
Set the primary engine unit for the current engine as the current component.
The primary unit must be ONLINE.
Set the state for the current engine unit to
ONLINE or STANDBY.
See…
242 iPlanet Integration Server • Process System Guide • August 2001
Managing Registrations with Conductor Script
Command
SetPrimary
Arguments unit_name
Function
Set the specified engine unit for the current engine as the primary unit. This will change the states of the engine units to make the specified unit ONLINE.
See…
Shutting Down Engine Components
You can shut down an individual component or all engine components using the
Shutdown command. This command shuts down the current component or engine.
If your engine components are standard iPlanet UDS partitions (interpreted by an iPlanet UDS ftexec) shutting down a component leaves the corresponding ftexec running.
Managing Registrations with Conductor Script
This section describes how to perform the following registration functions using
Conductor Script:
• making iIS library distributions
• registering iIS distributions
• unregistering iIS distributions
For background information on iIS library distributions and registration, including how to perform registration using iIS Console, see
Making iIS Library Distributions
You can use Conductor Script to perform operations normally performed through the iIS process development workshops, the operations performed with the File >
Compile and File > Distribute commands in the Process Development, Assignment
Rule, User Profile, and Validation workshops. These commands are used to create
TOOL projects from the various iIS plans and to make iIS library distributions from these TOOL projects. As explained in
“About Registration” on page 137 , it is these
iIS library distributions that are registered with iIS process engines.
Chapter 8 Using the Conductor Script Utility 243
Managing Registrations with Conductor Script
➤
To make an iIS library distribution
1.
Use the SetWorkspace command to make a particular workspace current.
2.
Use the
Open
command to open the current workspace.
3.
4.
5.
6.
Use the ListPlans command to display iIS plans in the workspace.
Use the
FindPlan
command to make a particular plan current.
Use the CompilePlan command to create a TOOL project for the plan.
Use the
MakeConductorDistribution
command to generate an iIS library distribution.
The library distribution is saved in the FORTE_ROOT/appdist directory on the central server node in your iIS system.
The commands needed to make iIS library distributions, except for
MakeConductorDistribution, are documented in the iPlanet UDS Fscript Reference
Guide and summarized in the table below:
Command
Close
IncludePublicPlan
Arguments
—— plan_name
ListPublicPlans
ListWorkspaces
NewWorkspace
Open
SetRepos
SetWorkspace
[match_string]
[show_unintegrated]
[show_internal]
[verbose_flag] workspace_name
[permissions]
[workspace_password] repository_name workspace_name
Function
Close the current workspace.
Include a publicly-available plan in the current workspace.
List the publicly available plans in the repository.
List the workspaces in the repository.
Create a new workspace in current repository.
Open the workspace specified on the last
SetWorkspace command.
Set the name of the repository for the next
Open command.
Set the name of the workspace for the next
Open command.
244 iPlanet Integration Server • Process System Guide • August 2001
Managing Registrations with Conductor Script
Command
AddSupplierPlan
Commit
CompilePlan
ExportPlan
FindPlan
ImportPlan
IntegrateWorkspace
ListPlans
MakeConductor
Distribution
RemoveSupplierPlan
ShowPlan
ShowWorkspace
UpdateWorkspace
Arguments plan_name
——
[force_flag]
file_name [node | ids] plan_name file_name
[comment]
[logfile_name]
[baseline_password]
[match_string] | [*]
—— plan_name
——
——
[logfile_name]
Function
Include a plan as a supplier plan to the current plan.
Commit changes to current workspace.
compile all out-of-date components in a plan.
Export all components of a plan to an export file.
Make the specified plan current.
Import a plan from the specified file.
Integrate the changes in this workspace into the shared repository.
List the plans in the current workspace.
Make an iIS library distribution from the current iIS plan. See
Remove a supplier plan from the current plan.
Display information about the current plan.
show the name of the current workspace and repository.
Update the current workspace with any changes in the system baseline since the last update.
Chapter 8 Using the Conductor Script Utility 245
Managing Registrations with Conductor Script
Registering iIS Library Distributions
After iIS library distributions have been generated, they can be registered with iIS process engines. You can register any number of iIS distributions with an engine using Conductor Script, but you can register only one type of distribution (user profile, process definition, and so on) with one engine at a time. To register multiple distributions, you can write a script that performs all the registrations that you want.
➤
To register an iIS distribution with an engine
1.
Use the
FindEngine
command to make a particular engine current.
2.
3.
Use the ListConductorDistributions command to display a list of iIS library distributions that are available for registration.
Use the appropriate
Register
command to register an available distribution of the corresponding type.
The commands needed to register iIS library distributions are documented in
Appendix A, “Conductor Script Commands” and summarized in the table below:
Command
FindEngine
ListConductor
Distributions
ListEngines
Arguments engine_name
[type]
——
Function
Set specified engine as the “current” engine.
The engine (nor any of its components) does not have to be running.
Display a list of the specified type of iIS library distributions available for registration. May include process definitions, assignment rule dictionaries, user profiles, and user validations.
Display a list of configured iIS process engines.
See…
246 iPlanet Integration Server • Process System Guide • August 2001
Managing Registrations with Conductor Script
Command
RegisterAlias
Arguments alias_name process_name engine_name environment
Function
Register the alias—representing a specified process running on a specified engine in a specified environment—with the current engine.
Register
AssignmentRules
Register
ProcessDefinition
Register
UserProfile
RegisterValidation
[dictionary_name] validation_name
Register all assignment rule dictionaries or the specified dictionary with the current engine.
[process_name] Register all process definitions or the specified process definition with the current engine.
[user_profile_name] Register all user profiles or the specified user profile with the current engine.
Register the specified validation with the current engine.
See…
Unregistering iIS Library Distributions
Normally you unregister an iIS distribution from an engine if it is no longer needed. Cold-starting an engine unregisters all registrations; however, if you want to be more selective, you can unregister specific distributions using Conductor
Script.
You can unregister any number of registered distributions, but you can only unregister one type of distribution (user profile, process definition, assignment rule dictionary…) from one engine at a time. To unregister multiple distributions, you can write a script that performs all the unregistrations that you want.
Chapter 8 Using the Conductor Script Utility 247
Managing Registrations with Conductor Script
➤
To unregister an iIS distribution from an engine
1.
Use the FindEngine command to make a particular engine current.
2.
Use the
ListRegistrations
command to display a list of iIS distributions that are registered with the current engine.
3.
Use the appropriate UnRegister command to unregister a distribution of the corresponding type.
The engine maintains only one validation, so registering a new validation implicitly unregisters the previous one.
The commands needed to unregister iIS distributions are documented in
Appendix A, “Conductor Script Commands” and summarized in the table below:
Command
FindEngine
ListEngines
ListRegistrations
Uninstall
UnRegisterAlias
Arguments engine_name
——
[type] name compatibility_level alias_name
Function
Set specified engine as the “current” engine.
The engine (nor any of its components) does not have to be running.
Display a list of all running and configured iIS process engines in the environment.
List all registered process definitions, assignment rule dictionaries, user profiles, user validations and aliases
(or just the specified type of distribution) for the current engine.
Deletes an iIS distribution of the specified name and level from the environment repository.
Unregister the specified alias from the current engine.
See…
248 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
Command
UnRegister
AssignmentRules
Arguments dictionary_name
[rule_name]
UnRegister
ProcessDefinition process_name
UnRegister
UserProfile user_profile_name
Function
Unregister all assignment rules (or just the specified assignment rule) in the specified assignment rule dictionary from the current engine.
Unregister the specified process definition from the current engine.
Unregister the specified user profile from the current engine.
See…
Managing Process Execution with
Conductor Script
This section describes how to perform some basic monitoring and management of process execution using Conductor Script. Normally these operations are more suited to iIS Console than to a command line utility. However, a number of
Conductor Script commands are available to perform the following management tasks:
• monitoring and managing sessions
• monitoring and managing executing processes
For background information on iIS process execution, including how to perform
process management using iIS Console, see Chapter 6, “Managing Process
Chapter 8 Using the Conductor Script Utility 249
Managing Process Execution with Conductor Script
Monitoring and Managing Engine Sessions
This section describes how to perform a number of tasks regarding the monitoring and managing of sessions:
• obtaining state information about a session
• suspending or terminating sessions
• sending messages to sessions
➤
To obtain state information about a session
1.
Use the FindEngine command to make a particular engine current
2.
Use the
ListSessions
command to display a list of sessions with the current engine.
3.
4.
5.
Use the CreateFilter command to filter the list of sessions, if desired.
Use the
ListSessions
command to display a list of filtered sessions.
Use the ShowSession command to display state information about a particular session.
➤
To suspend or terminate a session
1.
Display a list of sessions as described in Step 1 through Step 4 above.
2.
Enter SuspendSession , TerminateSession , SuspendAllSessions , or
TerminateAll Sessions to suspend or terminate one or all sessions.
NOTE A session that has in-progress two-phase commit operations can be suspended, but cannot be terminated. For more information, see
“Monitoring and Managing Two-Phase Commit” on page 199 .
➤
To send a message to one or more sessions
1.
Use the SendMessage or BroadcastMessage command, depending on whether you want to send a message to one session or to all sessions.
250 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
The commands needed to monitor and manage iIS sessions are documented in
Appendix A, “Conductor Script Commands” and summarized in the table below:
Command
BroadcastMessage
FindEngine
ListEngines
ListSessions
SendMessage
ShowSession
SuspendAllSessions
SuspendSession
TerminateAllSessions
TerminateSession
Arguments message_text priority engine_name
——
——
session_id, message_text priority session_id
—— session_id session_id
Function
Send a message with the specified priority to all sessions connected to the engine. The priority is a text string meaningful to the receiver.
Set specified engine as the
“current” engine. The engine (nor any of its components) does not have to be running.
Display a list of all running and configured iIS process engines in the environment.
List all sessions in the current engine.
Send a message with the specified priority to the specified session. The priority is a text string meaningful to the receiver.
Show details of the given session, including the activity list.
Suspend all active sessions in the current engine.
Suspend the specified active session.
Terminate all sessions in the current engine.
Terminate the specified session.
See…
Chapter 8 Using the Conductor Script Utility 251
Managing Process Execution with Conductor Script
Monitoring and Managing Process Execution
There are a number of situations where you are likely to want to monitor or intervene in process execution to resolve problems. Depending on the situation, you might wish to take some of the actions described in the following paragraphs.
Managing Process Instances
➤
To check the status of a process instance
1.
Use the FindEngine command to make a particular engine current
2.
Use the
ListProcesses
command to display a list of process instances in the current engine.
3.
4.
5.
Use the CreateFilter command to filter the list of process instances, if desired.
Use the
ListProcesses
command to display a list of filtered process instances.
Use the ShowProcess command to display information about a particular process instance.
The output shows information about the activities, timers, and process
attributes of the process instance (see Figure 6-2 on page 180
). You can get further information about these objects using their corresponding Show command.
➤ To abort a process instance
1.
Display a list of process instances as described in Step 1 through Step 4 above.
2.
Use the
AbortProcess
or
AbortAllProcesses
command, depending on whether you wish to abort a specific process instance or all process instances.
Managing Activity Instances
➤
To check the status of an activity instance
1.
Use the
FindEngine
command to make a particular engine current
2.
3.
4.
Use the ListActivities command to display a list of process instances in the current engine.
Use the
CreateFilter
command to filter the list of activities, if desired.
Use the ListActivities command to display a list of filtered activities.
252 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
5.
Use the
ShowActivity
command to display information about a particular activity.
The output shows information about the activity, its attributes and its linked timers. You can get further information about these objects using their corresponding Show command.
➤
To change the state of an activity
1.
Display a list of activities as described in
above.
2.
3.
Use the ShowActivity command to display information about a particular activity.
Use the
AbortActivity
,
ReadyActivity
, or
RollbackActivity
command to abort an activity, change its state from PENDING to READY, or change its state from ACTIVE to READY.
Managing Activity Queues
➤
To list the contents of an activity queue
1.
Use the
FindEngine
command to make a particular engine current.
2.
3.
4.
Use the ListActivityQueues command to display a list of queues in the current engine.
Use the
CreateFilter
command to filter the list of queues, if desired.
Use the ShowActivityQueue command to display a list of activities in a specified queue.
This command displays information about the activities in the queue. You can get further information about these activities using the ShowActivity command.
➤
To reprioritize an activity in a queue
1.
Display a list of activities in a queue as described in Step 1 through Step 4
above.
2.
Use the
ShowActivity
command to display information about a particular activity.
3.
Use the SetQueuedActivityPriority command to change the value of the queue prioritizing process attribute for the activity. The engine reorders the queue.
Chapter 8 Using the Conductor Script Utility 253
Managing Process Execution with Conductor Script
Managing Timers
➤
To check the status of a timer
1.
Use the FindEngine command to make a particular engine current.
2.
Use the
ListTimers
command to display a list of timers in the current engine.
3.
4.
5.
Use the CreateFilter command to filter the list of timers, if desired.
Use the
ListTimers
command to display a list of filtered timers.
Use the ShowTimer command to display information about a particular timer.
The output shows information about the timer, its state and its expiration time.
➤
To change the state of a timer or change its expiration time
1.
Display a list of timers as described in Step 1 through Step 4 above.
2.
Use the
ShowTimer
command to display information about a particular timer.
3.
Use the SetTimer , SetTimerDeadline , or SetTimerElapsed command to turn a timer on or off, or to change the expiration date or time, depending on whether the timer is a deadline timer or an elapsed timer.
Managing Process Attributes
➤
To check the value or lock state of a process attribute
1.
Use the FindEngine command to make a particular engine current.
2.
Use the
ListProcesses
command to display a list of process instances in the current engine.
3.
4.
5.
Use the CreateFilter command to filter the list of process instances, if desired.
Use the
ListProcesses
command to display a list of filtered process instances.
Use the ShowProcess command to display information about a particular process instance.
The output shows information about the process attributes of the process instance.
254 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
➤
To change the value of a process attribute
1.
Display a list of attributes as described in
2.
Use the
SetAttributeValue
command to set the value of any listed process attribute.
➤
To remove an attribute lock
1.
Display a list of attributes as described in
2.
Use the
RemoveReadLock
command to remove a read lock, or the
RemoveWriteLock
command to remove a write lock.
Checking for Bottlenecks in Process Execution
➤
To find a process bottleneck
1.
Use the
FindEngine
command to make a particular engine current.
2.
3.
4.
5.
6.
7.
8.
9.
Use the ListActivities command to display a list of activity instances in the current engine.
Use the
CreateFilter
command to filter the list of activity instances by process name.
Use the ListActivities command to display a list of filtered activity instances.
Look for an activity name with more than an average number of instances.
Use the CreateFilter command to filter the list of activity instances by the suspected bottleneck activity name.
Use the
ListActivities
command to display a list of filtered activity instances.
Check the state of activities in the listing.
Use the
ShowActivity
command to display more information about each particular activity instance to determine what is causing the bottleneck.
Chapter 8 Using the Conductor Script Utility 255
Managing Process Execution with Conductor Script
The commands needed to intervene in execution of an iIS process instance are
documented in Appendix A, “Conductor Script Commands” and summarized in
the table below:
Command
AbortActivity
Arguments process_id activity_name
AbortAllProcesses ——
AbortProcess
CompleteActivity
ConsultActivity
CreateActivity process_id process_id activity_name
process_id, activity_id state consultation_rule return_rule
[user_name1]
[other_info1]
[user_name2]
[other_info2]
process_id, activity_name
CreateFilter time_interval filter_expression
DelegateActivity process_id, activity_id state delegation_rule
[user_name]
[other_info] filter_id DeleteFilter
ListActivities ——
ListActivityQueues [process_name]
Function
Place the specified activity in the
ABORTED state.
Abort all process instances in the current engine.
Abort the specified process instance.
Change the state of the specified activity from ACTIVE to COMPLETED.
Delegate the specified activity (in the specified state) to consultant users using the specified consultation assignment rule. A consultant session returns the activity using the return_rule assignment rule. The user name and other info strings are supplied if required by the consultation and return assignment rules.
Create an activity of the specified name in the specified process instance and place it in the PENDING state.
Create a filter for events posted on the current engine object which conform to the specified filter expression.
Delegate the specified offered activity
(in the specified state) to other users using the specified delegation assignment rule. The user name and other info string are supplied if required by the delegation rule.
Delete the specified filter.
List all activities in the current engine.
Display activity queues for the specified process (or all activity queues) in the current engine.
See…
256 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
Command
ListFilters
ListProcesses
ListTimers
ReadyActivity
RemoveReadLock
RemoveWriteLock
RollbackActivity
SetAttributeValue
SetQueuedActivity
Priority
SetTimer
SetTimerDeadline
SetTimerElapsed
ShowActivity
Arguments
——
[short],
[name process_name]
——
process_id, activity_name process_id attribute_name process_id attribute_name process_id activity_name process_id attribute_name attribute_type value process_id activity_id prioritizing_value
Function
List all existing event filters for the current engine.
List process instances for a specified process (or all process instances) in the current engine, or list a summary of process instances by process name.
List all timers in the current engine.
Change the state of the specified activity from PENDING to READY.
Remove a shared lock on the specified process attribute.
Remove an exclusive lock on the specified process attribute.
Change the state of the specified activity from ACTIVE to READY.
Set the value of the specified attribute for a specified process instance.
See…
Reprioritize activities in an activity queue by setting the prioritizing process attribute for a specified activity to a specified value.
Set the specified timer to the specified state (ON, OFF, or no change) and resume operation (or reset the timer)
process_id timer_name state
[reset_control] process_id timer_name state expiration_time process_id timer_name state time_interval
process_id, activity_name
Set the specified deadline timer to the specified state (ON, OFF, or no change) and set a new expiration time.
Set the specified elapsed timer to the specified state (ON, OFF, or no change) and set a new elapsed time interval until expiration.
Show details of the specified activity.
Chapter 8 Using the Conductor Script Utility 257
Managing Process Execution with Conductor Script
Command Arguments
ShowActivityQueue process_name,
[queue_name]
ShowProcess process_id
ShowTimer
StartActivity
StartTimer
StopTimer process_id timer_name
process_id, activity_name session_id process_id timer_name process_id timer_name
Function
Display the contents of the specified queue (or all queues) for the specified process in the current engine.
Show details of specified process instance, including all activities and the values of all process attributes.
Show details of the specified timer.
See…
Change the state of the specified activity from READY to ACTIVE.
Start the specified timer. Place it in the
ON state.
Stop the specified timer. Place it in the
OFF state.
Monitoring and Managing Two-Phase Commit
Transactions
The iIS two-phase commit protocol facilitates the synchronization of iIS process engine operations with application transactions by making it possible to place iIS engine operations in a transactional context. For information on this capability, see
“Monitoring and Managing Two-Phase Commit” on page 199 .
As a system manager, you can monitor and manage these iIS transactions, as described in the following sections.
Monitoring Two-Phase Commit Operations
You can use Conductor Script commands to monitor the status of in-progress iIS engine operations, as indicated in the table below. These commands print out the transaction ID of any iIS operations that are in a PREPARE phase.
Command Arguments
ShowActivity process_id activity_id
Function
Indicates any in-progress two-phase commit transactions in the activity.
See…
258 iPlanet Integration Server • Process System Guide • August 2001
Managing Process Execution with Conductor Script
Command
ShowProcess
ShowSession
Arguments Function process_id Indicates any in-progress two-phase commit transactions in the process.
session_id Indicates whether the session has two-phase commit mode enabled, and if so, any in-progress transaction. For example, it may indicate the following:
Two phase commit mode is enabled.
There is a client operation
“CompleteActivity” in
PREPARE phase.
See…
Managing Two-Phase Commit Operations
If a session should be suspended for any of a number of reasons, any iIS engine transaction in a PREPARE phase is retained on the session, awaiting resolution
(commit or rollback). The process client application is normally responsible for resolving these transactions; however, in the case of failure, these transactions may be left permanently in the PREPARE phase. Because of this, it is up to a system manager to check for and resolve any transactions left in a PREPARE phase.
For example, a client application may perform an activity, but fail before it can notify the engine to commit the CompleteActivity operation. Similarly, the engine could fail before receiving the commit. Both these situations result in inconsistency of state information between the client application and engine.
To properly resolve iIS engine transactions in a PREPARE phase, however, you must investigate whether related application transactions were committed or aborted. How you do this depends on the details of the application and how it keeps track of transaction IDs.
You can use the following Conductor Script commands to identify and resolve transactions in a PREPARE phase:
Command
CommitTransaction
Argument session_ID transaction_ID
Function
Commits the in-progress iIS engine transaction for the specified session or transaction ID.
See…
Chapter 8 Using the Conductor Script Utility 259
Managing Process Execution with Conductor Script
Command
ListTransactions
Argument
RollbackTransaction session_ID transaction_ID
Function
Lists information for all in-progress iIS engine transactions (that is, those in a PREPARE phase) for all sessions in the current engine.
Rolls back the in-progress iIS transaction for the specified session or transaction ID.
See…
➤ To resolve transactions after a client or engine failure
1.
Start Conductor Script from a command line and invoke ListTransactions .
cscript >ListTransactions
The output of this command identifies all sessions, and their respective status, that have transactions in a PREPARE phase. For example, if a CreateProcess transaction had been prepared before the client crashed and there was only one session in progress, you would see output such as the following:
Session Name:s1 Id:200 Status:Suspended
TransactionId:My_Transaction_Id1 Current operation:
"CreateProcess"
2.
3.
Commit or roll back the prepared transaction: cscript >CommitTransaction 200
Verify the commit or rollback of the transaction: cscript >ShowSession 200
The output of the ShowSession command should indicate that the transaction has been resolved.
260 iPlanet Integration Server • Process System Guide • August 2001
Appendix A
Conductor Script Commands
This appendix is an alphabetically ordered reference of the Conductor Script commands.
Conductor Script is a command line utility built on top of the iPlanet UDS Fscript command utility. As such, it includes Fscript commands for performing repository-based operations, as well as a large number of iIS-specific commands.
This appendix documents only the iIS-specific Conductor Script commands. For documentation of Fscript Commands accessible through Conductor Script, see the
Fscript Reference Guide.
An introduction summarizes and groups the Conductor Script commands according to their function.
Conductor Script Command Summary
The following tables summarize Conductor Script commands and group them into the following categories, each of which represents a level within the hierarchy shown in
• environment mode commands
• engine mode commands
• component mode commands
261
Conductor Script Command Summary
Figure A-1 Hierarchy of Conductor Script Levels
Environment
Mode
Environment
Engine
Mode
Engine 2 Engine 2
Component
Mode
Governor
Engine 2
Database Service
Backup Engine Unit
Primary Engine Unit
Each Conductor Script command is defined on one of these levels. To use a command, you navigate the hierarchy, making either an engine or an engine component “current,” and then invoke the command.
NOTE Conductor Script also provides access to all iPlanet UDS Fscript commands (except for the Run, RunDistrib, and RunFile commands). Fscript is an iPlanet UDS command line interface that lets you create new plans and projects, examine components, define and modify classes, partition, test, and run distributed applications, and define and deploy libraries. For information on how to use
Fscript commands for writing and running Conductor Script scripts, see
Chapter 8, “Using the Conductor Script Utility.”
For more complete information on Fscript commands, see the iPlanet UDS
Fscript Reference Guide.
262 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Command Summary
Environment Mode Commands
The Conductor Script environment mode commands work only in the active environment. They are used mostly to specify the current engine and current node, and also to make library distributions that can be registered with iIS process engines.
Command
FindEngine
IIOPServer
Arguments engine_name
[start|stop|show]
ListConductor
Distributions
[type]
ListEngines ——
MakeConductor
Distribution
——
Function
Set specified engine as the
“current” engine. The engine (nor any of its components) does not have to be running.
Starts, stops, or displays information about the IIOP service needed to support
CORBA/IIOP iIS process client applications.
Display a list of the specified type of iIS library distributions available for registration. May include process definitions, assignment rule dictionaries, user profiles, and user validations.
Display a list of all running and configured iIS process engines in the environment.
Generate a library distribution for the current iIS plan. Plan must be created using the iIS process development workshops. (Automatically boosts compatibility level of distribution.)
See…
Appendix A Conductor Script Commands 263
Conductor Script Command Summary
Command
SetPassword
ShowEngine
Uninstall
Arguments
[old_password]
[new_password] engine_name name compatibility_level
Function
Set password protection on opening Conductor Script in your active environment. Once you set a password, other users may not open Conductor
Script (or iIS Console, or iPlanet UDS Environment
Console, or Escript) in that environment without using the password.
Display status of the specified engine.
Deletes an iIS distribution of the specified name and compatibility level from the environment repository. Normally performed after unregistering an iIS distribution from all engines in the environment.
See…
Engine Mode Commands: Engine Management
The Conductor Script engine mode commands work only for the current engine.
They are used mostly to start components and specify the current component.
Command
FindDBService
Arguments service_name
FindGovernor ——
Function
Set the specified database service for the current engine as the current component. The database service must be running.
Set the governor for the current engine as the current component. The governor must be running.
See…
264 iPlanet Integration Server • Process System Guide • August 2001
Command
FindNode
FindPrimary
FindUnit
SetPrimary
ShowConfiguration
ShowStatus
Shutdown
Arguments node_name
—— unit_name unit_name
——
——
——
StartDBService service_name priority
Conductor Script Command Summary
Function
Set the specified node as the “current” node. The node must exist in the environment.
Set the primary engine unit for the current engine as the current component. The primary unit must be ONLINE.
Set the specified engine unit for the current engine as the current component. The engine unit must be running.
Set the specified engine unit for the current engine as the primary unit. This will change the states of the engine units to make the specified unit ONLINE.
Display contents of the configuration file of the current engine. (No engine components need be running for this command to work.)
Display status of the current engine. (No engine components need be running for this command to work.)
Shut down the current engine. This shuts down the governor, all database services, and all engine units.
Start the specified database service for the current engine on the current node.
See…
Appendix A Conductor Script Commands 265
Conductor Script Command Summary
Command
StartEngine
StartGovernor
StartUnit
WaitForStartup
Arguments
[newLog]
[newState]
[newRegistration]
[cold]
—— unit_name
[cold] unit_name timeout
Function
Start all components of the engine as specified in the engine configuration file. (Includes various start options that create new engine database tables.)
Start the governor for the current engine on the current node.
Start the specified engine unit for the current engine on the current node. (Includes cold start option to create engine database.)
Wait the specified timeout period (in seconds) for the specified engine unit to start up, and prints an error message if engine unit does not start within specified time. Used for writing automated scripts.
See…
Engine Mode Commands: Process
Execution Management
There are a large number of Conductor Script commands that let you monitor and manage sessions, process execution, and registration—functions performed by the primary engine unit. These commands, nevertheless, are available in engine mode—when the engine is current. The Conductor Script commands for managing process execution are also available when the primary engine unit is current.
266 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Command Summary
Command
AbortActivity
AbortAllProcesses
AbortProcess
BroadcastMessage
CommitTransaction
CompleteActivity
ConsultActivity
CreateActivity
CreateFilter
Arguments process_id, activity_name
—— process_id message_text, priority session_ID transaction_ID process_id, activity_name process_id, activity_id state consultation_rule return_rule
[user_name1]
[other_info1]
[user_name2]
[other_info2] process_id, activity_name time_interval filter_expression
Function
Place the specified activity in the
ABORTED state.
Abort all process instances in the current engine.
Abort the specified process instance.
Send a message with the specified priority to all sessions connected to the engine. The priority is a text string meaningful to the receiver.
Commits the in-progress iIS transaction for the specified session or transaction ID.
Change the state of the specified activity from ACTIVE to
COMPLETED.
Delegate the specified activity (in the specified state) to consultant users using the specified consultation assignment rule. A consultant session returns the activity using the return_rule assignment rule. The user name and other info strings are supplied if required by the consultation and return assignment rules.
Create an activity of the specified name in the specified process instance and place it in the
PENDING state.
Create a filter for events posted on the current engine object which conform to the specified filter expression.
See…
Appendix A Conductor Script Commands 267
Conductor Script Command Summary
Command
DelegateActivity
DeleteFilter
FlushLog
ListActivities
ListActivityQueues
ListFilters
ListProcesses
ListRegistrations
ListSessions
ListTimers
ListTransactions
Arguments process_id, activity_id state delegation_rule
[user_name]
[other_info] filter_id
——
——
[process_name]
——
[short],
[name process_name]
[type]
——
——
Function
Delegate the specified offered activity (in the specified state) to other users using the specified delegation assignment rule. The user name and other info string are supplied if required by the delegation rule.
Delete the specified filter.
Remove all the data held in the history log database tables.
List all activities in the current engine.
Display activity queues for the specified process (or all processes) in the current engine.
List all existing event filters for the current engine.
List process instances for a specified process (or list all process instances) in the current engine, or list a summary of process instances by process name.
List all registered process definitions, assignment rule dictionaries, user profiles, user validations and aliases (or just the specified type of distribution) for the current engine.
List all sessions in the current engine.
List all timers in the current engine.
Lists information for all in-progress iIS engine transactions
(that is, those in a PREPARE phase) for all sessions in the current engine.
See…
268 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Command Summary
Command
ReadyActivity
RegisterAlias
Register
AssignmentRules
Arguments process_id, activity_name alias_name, process_name, engine_name, environment
[dictionary_ name]
Register
ProcessDefinition
Register
UserProfile
[process_name]
[user_profile_ name]
RegisterValidation validation_name
RemoveReadLock
RemoveWriteLock process_id, attribute_name process_id, attribute_name
RollbackActivity process_id, activity_name
RollbackTransaction session_ID transaction_ID
SendMessage
SetAttributeValue session_id, message_text, priority process_id attribute_name attribute_type value
Function
Change the state of the specified activity from PENDING to
READY.
Register the alias—representing a specified process running on a specified engine in a specified environment—with the current engine.
Register all assignment rule dictionaries or the specified assignment rule dictionary with the current engine.
Register all process definitions or the specified process definition with the current engine.
Register all user profiles or the specified user profile with the current engine.
Register the specified validation with the current engine.
Remove a shared lock on the specified process attribute.
Remove an exclusive lock on the specified process attribute.
Change the state of the specified activity from ACTIVE to READY.
Rolls back the in-progress iIS transaction for the specified session or transaction ID.
Send a message with the specified priority to the specified session.
The priority is a text string meaningful to the receiver.
Set the value of the specified attribute for a specified process instance.
See…
Appendix A Conductor Script Commands 269
Conductor Script Command Summary
Command
SetQueuedActivity
Priority
SetTimer
SetTimerDeadline
SetTimerElapsed
ShowActivity
ShowActivityQueue
ShowProcess
ShowSession
ShowTimer
StartActivity
StartTimer
StopTimer
Arguments process_id, activity_id prioritizing_value process_id, timer_name state
[reset] process_id, timer_name state expiration_time process_id, timer_name state time_interval process_id, activity_name process_name,
[queue_name] process_id session_id process_id, timer_name process_id, activity_name session_id process_id, timer_name process_id, timer_name
Function See…
Reprioritize activities in an activity queue by setting the prioritizing process attribute for a specified activity to a specified value.
Set the specified timer to the specified state (ON, OFF, or no change) and resume operation (or reset the timer)
Set the specified deadline timer to the specified state (ON, OFF, or no change) and set a new expiration time.
Set the specified elapsed timer to the specified state (ON, OFF, or no change) and set a new elapsed time interval until expiration.
Show details of the specified activity.
Display the contents of the specified queue (or all queues) for the specified process in the current engine.
Show details of specified process instance, including all activities and the values of all process attributes.
Show details of the given session, including the activity list.
Show details of the specified timer.
Change the state of the specified activity from READY to ACTIVE.
Start the specified timer. Place it in the ON state.
Stop the specified timer. Place it in the OFF state.
270 iPlanet Integration Server • Process System Guide • August 2001
Command
SuspendAllSessions
Arguments
——
SuspendSession
TerminateAllSessions session_id
TerminateSession
UnRegisterAlias
UnRegister
AssignmentRules session_id alias_name dictionary_ name
[rule_name]
UnRegister
ProcessDefinition
UnRegister
UserProfile process_name user_profile_ name
Conductor Script Command Summary
Function
Suspend all active sessions in the current engine.
Suspend the specified active session.
Terminate all sessions in the current engine.
Terminate the specified session.
Unregister the specified alias from the current engine.
Unregister all assignment rules (or just the specified assignment rule) in the specified assignment rule dictionary from the current engine.
Unregister the specified process definition from the current engine.
Unregister the specified user profile from the current engine.
See…
Component Mode Commands
The Conductor Script engine component mode commands work only for the current component.
Appendix A Conductor Script Commands 271
Conductor Script Command Summary
Generic component
A few commands work for any current component.
Command
ShowStatus
ShowLogFlags
ModLogFlags
Shutdown
FindParentEngine
Parameters
[short]
——
+(message_filters)
–(message_filters)
——
——
Function
Display the status of the current component. If the current component is an engine unit in the
ONLINE state, then this command shows the full instrumentation implemented for all the engine’s internal manager objects.
Display the logger message filters (logger flags) set for the current component (partition logger settings).
modify the logger message filters (logger flag) set for the current component.
Shut down the current component.
Make the component’s parent engine current.
Puts you in “engine mode.”
See…
Engine Unit
One command applies only if the current component is an engine unit.
Command
SetState
Parameters state
Function
Set the state for the current engine unit to ONLINE or STANDBY.
See…
272 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
Conductor Script Commands
The following is a listing of all Conductor Script commands.
AbortActivity
The AbortActivity command aborts the specified activity, placing it in the
ABORTED state.
AbortActivity process_id activity_name
Argument Description process_id The process instance in which the activity was created.
activity_name The name of the activity.
The AbortActivity command is only available when an engine is current. Use the
FindEngine Script command to set the current engine.
When you issue the
AbortActivity
command, the engine performs the following actions:
• discards pending process attribute updates—rolls back changes that were made in performing the activity and frees locks on process attributes associated with the activity
• evaluates the activity’s OnAbort method, if one is specified in the process definition
• evaluates the activity’s OnAbort routing methods—if none are specified, the engine by default aborts the process
• checks for a process stall condition—when all other activity instances are either
COMPLETED or PENDING (no activities are in ACTIVE or READY state) and no timers are active—and aborts the process if a stall condition is detected.
• deletes the ABORTED activity
Appendix A Conductor Script Commands 273
Conductor Script Commands
AbortAllProcesses
The AbortAllProcesses command aborts all process instances for the current engine.
AbortAllProcesses
The AbortAllProcesses command is only available for the current engine. Use the
FindEngine Script command to set the current engine and the ListProcesses
Script command to display a list of process instances before aborting them.
When you issue the
AbortAllProcesses
command, the engine posts an alarm for each process instance to be aborted.
AbortProcess
The AbortProcess command aborts a specified process instance for the current engine.
AbortProcess process_id [process_id…]
Argument process_id
Description
The specified process instance. (A list of up to ten process_ids separated by spaces is supported.)
The AbortProcess command is only available for the current engine. Use the
FindEngine Script command to set the current engine and the ListProcesses
Script command to display a list of process instances before selecting the process to abort.
When you issue the
AbortProcess
command, the engine posts an alarm for the process instance to be aborted.
274 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
BroadcastMessage
The BroadcastMessage command sends a message to all active sessions on the current engine.
BroadcastMessage message urgency
Argument Description message An alphanumeric string that constitutes the text of the message. Message text must be enclosed in double quotes.
urgency One of two specified string constants: INFORMATIONAL or CRITICAL.
The
BroadcastMessage
command is only available when an engine is current. Use the
FindEngine
Script command to set the current engine.
The BroadcastMessage command is used to notify all sessions about a pending administrative action, such as changing the state of the primary engine from
ONLINE to STANDBY.
CommitTransaction
The
CommitTransaction
command commits an in-progress iIS engine transaction
(that is, one in a PREPARE phase). For details on two-phase commit operations, see
“Monitoring and Managing Two-Phase Commit” on page 199 .
CommitTransaction {session_ID | transaction_ID}
Argument session_ID
Description
The identifier of the session which has a transaction in a PREPARE phase. A session can have only one in-progress two-phase transaction.
transaction_ID The identifier of the transaction in a PREPARE phase.
To roll back an in-progress iIS engine transaction, use the
RollbackTransaction command. To list all in-progress iIS transactions for a given engine, use the
ListTransactions
command.
Appendix A Conductor Script Commands 275
Conductor Script Commands
CompleteActivity
The CompleteActivity command completes the specified activity, putting it in
COMPLETED state.
CompleteActivity process_id activity_name
Argument Description process_id The process instance in which the activity was created.
activity_name The name of the activity.
The CompleteActivity command is only available when an engine is current. Use the FindEngine Script command to set the current engine.
When you issue the
CompleteActivity
command, the engine performs the following actions:
• commits pending process attribute updates—saves changes that were made in performing the activity and frees locks on process attributes associated with the activity
• evaluates the activity’s OnComplete method, if one is specified
• evaluates the activity’s OnComplete router methods
• checks for a process stall condition—when all other activity instances are either
COMPLETED or PENDING (no activities are in ACTIVE or READY state) and no timers are active—and aborts the process if a stall condition is detected
• deletes the COMPLETED activity
ConsultActivity
The
ConsultActivity
command hands off the specified offered activity to other users using the specified consultation assignment rule. A consulted session returns the activity using an assignment rule specified by the return_rule.
276 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
ConsultActivity process_id activity_id state consultation_rule
return_rule [user_name1 [other_info1] [user_name2 [other_info2]]]
Argument process_id
Description
The process instance in which the activity was created.
activity_id state user_name1
The activity instance to be delegated.
The state of the activity instance to be delegated (READY or
ACTIVE).
consultation_rule The assignment rule used to hand off the activity to consulted sessions.
return_rule The assignment rule used to return the activity to delegating users.
The user name, if any, required by the consultation_rule. If this argument is not required, put a null argument enclosed in double quotes (““).
other_info1 user_name2 other_info2
Otherinfo string of the user name passed to the consultation_rule, if any. If this argument is not required, put a null argument enclosed in double quotes (““).
The user name if any, required by the return_rule.
Otherinfo string of the user name passed to the return_rule, if any.
The ConsultActivity command is only available when an engine is current. Use the FindEngine Script command to set the current engine.
The
ConsultActivity
command is used to hand off the work associated with an offered activity to someone else, one or more consulted users, who then return it to one or more originating users. The activity must be in READY or ACTIVE state before the
ConsultActivity
command is used. If the activity is in an ACTIVE state, any open attributes are updated as necessary, the accessor is closed, and the activity’s state is changed to READY. The activity is offered to sessions as permitted by the consultation assignment rule.
NOTE The state parameter is used to confirm that the current state of the activity is what you expect when you issue the ConsultActivity command. If the state has changed, the engine does not execute the command.
Appendix A Conductor Script Commands 277
Conductor Script Commands
The user_name1 and other_info1 arguments must be supplied if required by the consultation assignment rule. For example, if a consultation rule named
“ManagerOf” looks for the manager of the user who is handing off to a consultant, then this user’s user name and other info (in this case the manager’s name) would be passed to the ManagerOf assignment rule. This behavior is similar in function to the linked activity mechanism described in the iIS Process Development Guide.
Once the consulted user has completed work on the activity, the activity is offered back according to the assignment rule specified by return_rule. The user_name2 and other_info2 arguments must be supplied if required by the return_rule. For example, if a return_rule assignment rule named “SameAs” looks for the original user who passed off the activity to a consultant, then that original user’s name would be passed to the return_rule assignment rule.
Once the user to whom the activity is returned has completed (or aborted) the activity, process execution continues as specified in the process definition.
CreateActivity
The CreateActivity command creates the specified activity, placing it in
PENDING state.
CreateActivity process_id activity_name
Argument process_id activity_name
Description
The process instance in which the activity is to be created.
The name of the activity.
The CreateActivity command is only available when an engine is current. Use the FindEngine Script command to set the current engine.
When the
CreateActivity
command creates an activity, it is placed in PENDING state. Its Trigger method is evaluated each time the router method of a preceding activity is evaluated as TRUE or when a process attribute changes value. When the trigger conditions are fulfilled, the activity can transition into READY state. To override the trigger conditions, you can use the
ReadyActivity
Script command after creating the activity.
278 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
CreateFilter
The CreateFilter command creates a filter for events posted on the current engine object.
CreateFilter time_interval filter_expression
Argument time_interval filter_expression
Description
The time during which the filter batches up events before reporting them, in milliseconds.
Expression specifying filter criteria.
The
CreateFilter
command is only available when an engine is current. Use the
FindEngine
Script command to set the current engine.
The CreateFilter command assigns a filter ID to the new filter.
The filter_expression argument provides the criteria used to filter the universe of events posted by the engine. These events include all state changes to sessions, process instances, and activities, as well as changes in process attributes. The filter expression uses a number of comparison operators to specify three filter expression elements. The three elements—type, object class, and object instance—and the operators are described below:
Event Type
Type
Object creation
Object deletion
Attribute change 3
Alarm report 4
Value
1
2
Description
Events reporting creation of sessions, process instances, or activities
Events reporting deletion of sessions, process instances, or activities
Events reporting changes in process attribute values
Events of a particularly important nature regarding process execution
Appendix A Conductor Script Commands 279
Conductor Script Commands
Object Class
Class Value
Session 1
Process instance 2
Activity
Engine
3
4
Timer
Registration
5
6
Description
Events involving sessions
Events involving process instances
Events involving activities
Events involving engine objects
Events involving timers
Events involving registrations
Object Instance
This element specifies a particular instance identification, if desired—for example, a session name, activity name, or process ID.
Class
Session
Process instance
Activity
Instance Identification session_id process_id process_id and activity_id
Operators
The table below shows the different operators that can be used with the filter elements to specify the filter criteria. The two unary operators at the top of the table have higher priority than the binary operators that follow, which have higher priority than the logical operators at the bottom of the table.
Operator
?
~
=
<>
<
Meaning instance identification present (in the event) instance identification not present (in the event) equal not equal less than
280 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
Operator
>
<=
>= and or not
Meaning greater than less than or equal to greater than or equal to logical and logical or logical not
Examples
Some example filter expressions follow:
Filter Expression class = 1 and name = “Session1” type =1 and class = 2 type = 4 class = 3 and process_id = 45
Meaning
Filter all events from the session whose name is
“Session1”.
Filter all process creations.
Filter all alarms.
Filter all events from the activities of process 45.
When the CreateFilter command sets up the filter as specified, events that satisfy the filter expression are printed to the screen.
DelegateActivity
The
DelegateActivity
command delegates the specified offered activity to other users using the specified delegation assignment rule.
DelegateActivity process_id activity_id state delegation_rule
[user_name [other_info]]
Argument process_id activity_id
Description
The process instance in which the activity was created.
The activity instance to be delegated.
Appendix A Conductor Script Commands 281
Conductor Script Commands
Argument other_info
Description state The state of the activity instance to be delegated (READY or
ACTIVE).
delegation_rule The assignment rule used to assign the activity to sessions, that is, to delegated users.
user_name The user name, if any, required by the delegation_rule. If this argument is not required, place a null argument in quotation marks (““).
Otherinfo string of the user name passed to the delegation_rule, if any.
The DelegateActivity command is only available when an engine is current. Use the FindEngine Script command to set the current engine.
The
DelegateActivity
command is used to hand off the work associated with an offered activity to someone else: one or more delegated users. The delegated activity must be in READY or ACTIVE state before the
DelegateActivity command is used. If the activity is in ACTIVE state, any open attributes are updated as necessary, the accessor is closed, and the activity’s state is changed to
READY. The activity is then offered to sessions as permitted by the delegation assignment rule.
NOTE The state parameter is used to confirm that the current state of the activity is what you expect when you issue the DelegateActivity command. If the state has changed, the engine does not execute the command.
The user_name and other_info arguments must be supplied if required by the delegation assignment rule. For example, if a delegation rule named “ManagerOf” looks for the manager of the delegator, then the delegator’s user name and other info (in this case the manager’s name) would be passed to the ManagerOf assignment rule. This behavior is similar in functionality to the linked activity mechanism described in the iIS Process Development Guide.
Once the delegated user has completed (or aborted) the activity, process execution continues as specified in the process definition.
282 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
DeleteFilter
The DeleteFilter command deletes the specified event filter in the current engine.
DeleteFilter filter_id
Argument filter_id
Description
The specified filter.
The
DeleteFilter
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
You can to use the ListFilters Script command to display a list of filters before selecting the filter to delete.
FindDBService
The
FindDBService command sets the specified database service for the current engine as the current component.
FindDBService service_name
Argument Description service_name The specified database service.
The FindDBService command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine. The specified database service must also be running.
The
FindDBService
command is normally used to check the status of a specific database service (using the
ShowStatus
Script command) or to shut it down (using the
Shutdown
Script command).
Appendix A Conductor Script Commands 283
Conductor Script Commands
FindEngine
The FindEngine command sets the specified engine as the current engine.
FindEngine engine_name
Argument Description engine_name The specified engine.
The
FindEngine
command is always available. The specified engine need not be running.
You can use the ListEngines Script command to display the list of engines. The
FindEngine command is normally the first command issued to perform any engine management, database management, or process execution management tasks.
FindGovernor
The
FindGovernor
command sets the governor for the current engine as the current component.
FindGovernor
The
FindGovernor
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine. The governor must also be running.
The FindGovernor command is normally used to check the status of the governor
(using the ShowStatus Script command) or to shut it down (using the Shutdown
Script command).
284 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
FindNode
The FindNode command sets the specified node as the current node.
FindNode node_name
Argument Description node_name The specified node. Must be in same environment as the engine.
The
FindNode
command is available only for the current engine.
The FindNode command is normally used to start engine components (using the
StartGovernor , StartDBService , and StartUnit Script commands).
FindParentEngine
The
FindParentEngine
command makes the component’s parent engine current.
FindParentEngine
The
FindParentEngine
command is available only when an engine component is current.
The FindParentEngine command is used to navigate to the current engine when one of its components is current and you want to make another of its components current. (The Find and Start component Script commands are only available when an engine is current.)
FindPrimary
The
FindPrimary
command sets the primary engine unit for the current engine as the current component.
FindPrimary
The
FindPrimary
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine. The primary engine unit must also be running.
Appendix A Conductor Script Commands 285
Conductor Script Commands
The
FindPrimary
command is normally used to check the status of the primary engine unit (using the
ShowStatus
Script command), to change its state (using the
SetState
and
Shutdown
Script commands), and to perform process execution and engine database management tasks.
FindUnit
The FindUnit command sets the specified engine unit for the current engine as the current component.
FindUnit unit_name
Argument Description unit_name The specified engine unit.
The
FindUnit
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine. The specified engine unit must also be running.
The FindUnit command is normally used to check the status of a specific engine unit (using the ShowStatus Script command) or to change its state (using the
SetState and Shutdown Script commands). If the engine unit is the primary engine unit then you can also perform process execution and engine database management tasks.
FlushLog
The
FlushLog
command removes all the data held in the history log database tables of the current engine.
The FlushLog command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
You can use the
FlushLog
command when the history log database grows too large. Typically you would first back up the current database or export the history log tables.
286 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
IIOPServer
The IIOPServer command starts, stops, or displays information about the IIOP service needed to support CORBA/IIOP iIS process client applications.
IIOPServer [start|stop|show]
The IIOPServer command is always available.
The
IIOPServer
command is used to start up the IIOP service installed by the iIS installer program on the central server node in your iPlanet UDS environment. The
IIOP service is required for CORBA/IIOP client applications to access an iIS process engine.
ListActivities
The ListActivities command displays all activities in the current engine.
ListActivities
The ListActivities command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
ListActivities
command displays activities in all process instances of all registered process definitions. For each activity, the
ListActivities
command displays the following information: activity name, activity ID, activity state, and process name.
ListActivityQueues
The ListActivityQueues command displays queues either for the specified process or for all processes in the current engine.
ListActivityQueues [process_name]
Argument Description process_name The specified process. If not specified then all queues in the engine are displayed.
The ListActivityQueues command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Appendix A Conductor Script Commands 287
Conductor Script Commands
The
ListActivityQueues
command displays all activity queues in a specified process definition. For each queue the
ListActivityQueues
command displays the process name and the queue name.
ListConductorDistributions
The ListConductorDistributions command displays a list of the specified type of library distribution (generated from iIS process development workshops) available for registration.
ListConductorDistributions [type]
Argument Description type The specified distribution type: process definition, assignment rule dictionary, or user profile.
The ListConductorDistributions command is always available. If the distribution type is not specified, all types are listed, grouped by type.
The
ListConductorDistributions
command is used to display a list of library distributions of the appropriate type that you might want to register using the
Register
Script command. For each distribution, the
ListConductorDistributions
command displays the distribution name and the distribution type.
You can generate the libraries listed by this command using the FindPlan Fscript command to make a specified plan current, and then issuing the
MakeConductorDistribution Script command to create the library distribution on the central server of the active environment. The list of iIS libraries accessed by
ListConductorDistributions is maintained by the WFEngAgent service running on the central server node.
288 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
ListEngines
The ListEngines command displays a list of all running and configured engines in the current environment.
ListEngines
The ListEngines command is always available.
The list displayed includes all configured engines, indicating engines that are
ONLINE. It also includes engines that are ONLINE for which there is no configuration file.
ListFilters
The ListFilters command displays all sieves in the current engine.
ListFilters
The ListFilters command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
For each filter the
ListFilters
command displays the filter ID, the time interval, and the filter expression.
ListProcesses
The ListProcesses command displays process instances for a specified process
(or displays all process instances) in the current engine, or lists a summary of process instances by process name.
ListProcesses [short] [name process_name]
Argument process_name
Description
The specified process.
The
ListProcesses
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The ListProcesses command displays process instances.
Appendix A Conductor Script Commands 289
Conductor Script Commands
Options
• If you use the short option, the command displays a summary of process instances by process definition.
• If you use the name
option, the command displays all process instances for the specified registered process definition.
• If you do not specify an option, it displays all process instances in the current engine.
For any given process instance, you can monitor or manage its activities, timers, attributes, and attribute locks. For each process instance, the
ListProcesses command displays the following information: process name, the process definition version, the value of the primary process attribute, the primary process attribute name, the process instance ID, and the process creation time.
ListRegistrations
The ListRegistrations command displays distributions of the specified type (or all types) registered with the current engine.
ListRegistrations [type]
Argument Description type The specified component type: process definition, assignment rule dictionary, user profile, uservalidation, or alias.
The ListRegistrations command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine. If the type is not specified, all types are listed, grouped by type.
You can delete any registered entity from the current engine’s registration database using the appropriate
UnRegister
Script command. You can register additional entities using the appropriate
Register
Script command. For each registered entity the
ListRegistrations
command displays the name of the registered component and the type.
290 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
ListSessions
The ListSessions command displays all sessions maintained by the current engine.
ListSessions
The ListSessions command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
For any given session, you can change its state using the
SuspendSession
or
TerminateSession
Script command. For each session, the
ListSessions command displays the following information: session name, session ID, user, session state (ACTIVE or SUSPENDED), and the number of items on the session activity list.
ListTimers
The ListTimers command displays all timers in the current engine.
ListTimers
The ListTimers command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
ListTimers
command displays timers in all process instances of all registered process definitions. For each timer, the
ListTimers
command displays the timer name, the process ID, the state, and the expiration time and date.
ListTransactions
The ListTransactions command lists all in-progress iIS engine transactions for all sessions for a specified engine. For details on two-phase commit operations, see
“Monitoring and Managing Two-Phase Commit” on page 199 .
To roll back an in-progress iIS engine transaction, use the
RollbackTransaction command. To commit an in-progress iIS engine transaction, use the
CommitTransaction
command.
Appendix A Conductor Script Commands 291
Conductor Script Commands
MakeConductorDistribution
The MakeConductorDistribution command generates a library distribution for the current plan. The plan must be created in the iIS process development workshops.
MakeConductorDistribution
The MakeConductorDistribution command is always available; however, it requires that a plan created in the iIS process development workshops also be current. To make such a plan current, use the FindPlan Script command (see
“Making iIS Library Distributions” on page 243 ).
NOTE Unlike the generation of library distributions in the iPlanet UDS development environment, generating library distributions with
MakeConductorDistribution
automatically increases the compatibility level of the current plan. iIS developers must keep track of the compatibility level of any iIS plans they export, noting that their compatibility level will change after generation of library distributions.
After issuing the
MakeConductorDistribution
command, you can use the
ListConductorDistributions
Script command to confirm that the library distribution has been generated.
ModLogFlags
The ModLogFlags command modifies the log message filters set for the current component.
ModLogFlags {+(message_filters) | -(message_filters)}
Argument
+(message_filters)
-(message_filters)
Description
Turn on the log flag settings given in the parentheses.
Turn off the log flag settings given in the parentheses.
The ModLogFlags command is only available when an engine component is current.
292 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
To start logging, use the ’+’ followed by a set of message filters in parentheses. To stop logging, use the ’-’ followed by a set of message filters in parentheses.
The settings specified with the ModLogFlags command modify the log message filters that were set when the current component started up, based on the
FORTE_LOGGER_SETUP environment variable.
An example of the
ModLogFlags
command is: cscript> ModLogFlags +(trc:wr:2:2)
This filter specifies that all messages about sessions created in the engine —but not a lot of detail— be written to the primary engine unit’s log file (on the server node on which the primary engine unit is running). For information on iIS message filters, see
“Messages and Message Filters” on page 212
.
ReadyActivity
The ReadyActivity command changes the state of the specified activity from
PENDING to READY.
ReadyActivity process_id activity_name
Argument process_id activity_name
Description
The process instance in which the activity was created.
The name of the activity.
The ReadyActivity command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
ReadyActivity
command does not apply to activities that do not pass through
READY state, such as subprocess activities.
Before changing the state of an activity from PENDING to READY, the engine first evaluates the activity’s Ready expression if one is specified in the process definition.
Appendix A Conductor Script Commands 293
Conductor Script Commands
RegisterAlias
The RegisterAlias command registers the specified subprocess alias in the current engine’s registration database. For more information on aliases, see
.
RegisterAlias alias_name process_name engine_name environment
Argument Description alias_name The name of the alias (same as the process name).
process_name The name of the process referenced by the specified alias.
engine_name environment
The name of the engine on which the specified process is executed.
The name of the environment in which the specified engine is located.
The RegisterAlias command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
RegisterAlias
command registers an alias only if an alias of the same name is not already registered.
RegisterAssignmentRules
The RegisterAssignmentRules command registers the specified assignment rule dictionary (or all available assignment rule dictionaries) in the current engine’s registration database.
RegisterAssignmentRules [dictionary_name]
Argument Description dictionary_name The name of the assignment rule dictionary to be registered. If not specified, then all available assignment rule dictionaries are registered.
The
RegisterAssignmentRules
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
294 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
Use the
ListConductorDistributions
Script command to display a list of distributions available for registration (you can filter the list for assignment rule dictionaries). The
RegisterAssignmentRules
command registers an assignment rule dictionary only if a dictionary of the same name and compatibility level is not already registered.
RegisterProcessDefinition
The RegisterProcessDefinition command registers the specified process definition (or all available process definitions) in the current engine’s registration database.
RegisterProcessDefinition [process_name]
Argument process_name
Description
The name of the process definition to be registered. If not specified, then all available process definitions are registered.
The RegisterProcessDefinition command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Use the
ListConductorDistributions
Script command to display a list of distributions available for registration. You can filter the list for process definitions.
The
RegisterProcessDefinition
command registers a process definition only if a process definition of the same name and compatibility level is not already registered.
RegisterUserProfile
The RegisterUserProfile command registers a user profile in the current engine’s registration database.
RegisterUserProfile [user_profile_name]
Argument Description user_profile_name The name of the user profile to be registered. If not specified, then all available user profiles are registered.
Appendix A Conductor Script Commands 295
Conductor Script Commands
The
RegisterUserProfile
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
Use the ListConductorDistributions Script command to display a list of distributions available for registration. You can filter the list for user profiles. You can register multiple user profiles with an engine if each has a unique name, but you can register only one compatibility level of a user profile of a given name. The
RegisterUserProfile command registers a user profile only if a user profile of the same name is not already registered.
RegisterValidation
The
RegisterValidation
command registers a validation in the current engine’s registration database.
RegisterValidation validation_name
Argument Description validation_name The name of the validation.
The RegisterValidation command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Use the
ListConductorDistributions
Script command to display a list of distributions available for registration. You can filter the list for validations. You can only register one validation with an engine (any previous registration will be implicitly unregistered). The
RegisterValidation
command registers a validation only if a validation of the same name and compatibility level is not already registered.
296 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
RemoveReadLock
The RemoveReadLock command removes a read lock on the specified process attribute.
RemoveReadLock process_id attribute_name
Argument Description process_id The process instance of the specified attribute.
attribute_name The name of the process attribute that is locked.
The RemoveReadLock command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
RemoveReadLock
command lets you remove a read lock that remains due to some unusual circumstance. Completing or aborting an activity should remove any locks placed on a process attribute; however, if a session is unexpectedly terminated, locks might remain in place.
RemoveWriteLock
The RemoveWriteLock command removes a write lock on the specified process attribute.
RemoveWriteLock process_id attribute_name
Argument Description process_id The process instance of the specified attribute.
attribute_name The name of the process attribute that is locked.
The RemoveWriteLock command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
RemoveWriteLock
command lets you remove a write lock that remains due to some unusual circumstance. Completing or aborting an activity should remove any locks placed on a process attribute; however, if a session is unexpectedly terminated, locks might remain in place.
Appendix A Conductor Script Commands 297
Conductor Script Commands
RollbackActivity
The RollbackActivity command changes the state of the specified activity from
ACTIVE to READY.
RollbackActivity process_id activity_name
Argument process_id activity_name
Description
The process instance in which the activity was created.
The name of the activity.
The RollbackActivity command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
RollbackActivity
command does not apply to activities that do not pass through READY state, such as SubProcess, First, and Last activities.
When you issue the RollbackActivity command, the engine performs the following actions:
• Discards pending process attribute updates—rolls back changes that were made in performing the activity and frees locks on process attributes
• Changes the activity state from ACTIVE to READY
• Posts an ActivityListUpdate event to all sessions associated with the activity
• If the activity is an offered activity, the engine reassigns it to sessions based on the activity’s assignment rules
• If the activity is a queued activity, the engine places it back on the queue to which it was assigned
• If the activity is an automatic activity, the engine automatically places it in
ACTIVE state, and re-evaluates the AutoAction expression for the activity.
RollbackTransaction
The
RollbackTransaction
command rolls back (undoes) an in-progress iIS engine transaction (that is, one in a PREPARE phase). For details on two-phase commit
operations, see “Monitoring and Managing Two-Phase Commit” on page 199
.
298 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
RollbackTransaction {session_ID | transaction_ID}
Argument Description session_ID The identifier of the session which has a transaction in a PREPARE phase. A session can have only one in-progress two-phase transaction.
transaction_ID The identifier of the transaction in a PREPARE phase.
To commit an in-progress iIS engine transaction, use the CommitTransaction command. To list all in-progress iIS engine transactions for a given engine, use the
ListTransactions command.
SendMessage
The
SendMessage
command sends a message to a specified sessions on the current engine.
SendMessage session_id message urgency
Argument session_id message urgency
Description
The specified session.
An alphanumeric string that constitutes the text of the message.
Message text must be enclosed in double quotes.
One of two specified string constants: INFORMATIONAL or
CRITICAL.
The SendMessage command is only available when an engine is current. Use the
FindEngine Script command to set the current engine.
The
SendMessage
command is used to notify a session about a pending administrative action, such as a request for consultation, pending suspension of the session, and so forth.
Appendix A Conductor Script Commands 299
Conductor Script Commands
SetAttributeValue
The SetAttributeValue command sets a specified process attribute in the current engine to a specified value.
SetAttributeValue process_id attribute_name attribute_type value
Argument Description process_id The process instance of the specified attribute.
attribute_name The name of the process attribute that is to be set.
attribute_type The data type of the attribute value.
value The value to be assigned to the attribute. String values must be enclosed in within double quotes.
The
SetAttributeValue
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The SetAttributeValue command lets you change a specified process attribute value of a process instance (for example, a priority attribute, which affects the routing between activities).
SetPassword
The
SetPassword
command sets password protection for opening Conductor
Script in your active environment. After you set a password, other users cannot open Conductor Script (or iIS Console, or iPlanet UDS Environment Console, or iPlanet UDS Escript) in that environment without using the password.
SetPassword [old_password] [new_password]
Argument old_password new_password
Description
The current existing password.
The new (or null) password.
The
SetPassword
command is always available. The specified engine need not be running to use the
SetPassword
command.
300 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
You can use the
SetPassword
Script command to set a password, change an existing password to a new password, or delete an existing password.
SetPrimary
The SetPrimary command sets the specified engine unit for the current engine as the primary unit.
SetPrimary unit_name
Argument Description unit_name The specified engine unit.
The
SetPrimary
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine. The specified engine unit must also be running.
The SetPrimary command is normally used to switch the role of the primary and backup engine units. If the specified engine unit is the backup unit, the primary unit will be placed in a STANDBY state and the backup unit will then be placed
ONLINE. If the specified engine unit is the primary unit, nothing will be done.
The
SetPrimary
command makes the specified engine unit the current component.
SetQueuedActivityPriority
The SetQueuedActivityPriority command reprioritizes activities in an activity queue by setting the prioritizing process attribute for a specified activity to a specified value.
SetQueuedActivityPriority process_id activity_id prioritizing_value
Argument Description process_id activity_id
The process instance in which the activity was created.
The activity ID of the specified activity.
prioritizing_value The value to be assigned to the queue prioritizing process attribute of the process instance.
Appendix A Conductor Script Commands 301
Conductor Script Commands
The
SetQueuedActivityPriority
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The SetQueuedActivityPriority command lets you change the ordering of activities in a queue by changing the value of the queue prioritizing attribute for a specified activity in the queue. Doing so causes the engine to place the specified activity instance in a different position in the queue.
SetState
The
SetState
command sets the state of the specified engine unit.
SetState state
Argument state
Description
The state to which the engine unit will be set: ONLINE or STANDBY.
The SetState command is only available if the current component is an engine unit. Use the FindEngine Script command to set the current engine and the
FindUnit Script command to make the desired engine unit current.
The
SetState
command is normally used to take the primary engine unit offline for administrative functions and then to restore it to ONLINE state afterwards.
Placing the primary engine unit in STANDBY state will not cause the partner engine unit to come ONLINE.
SetTimer
The SetTimer command sets the specified timer to the specified state and resumes operation (or resets the timer).
SetTimer process_id timer_name state [reset]
Argument process_id timer_name state
Description
The process instance of the specified timer.
The name of the specified timer.
The specified new state: ON, OFF, or no change.
302 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
The
SetTimer
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
You can use the SetTimer command to turn any timer on or off, to reset an elapsed timer to its original time interval, or to do both. To set new timer expiration times, use the SetTimerDeadline or SetTimerElapsed, depending on the type of timer. The reset option lets you use the SetTimer command to reset the timer, rather than resume operation. This option applies only to elapsed timers.
SetTimerDeadline
The
SetTimerDeadline
command sets the specified deadline timer to the specified state (ON, OFF, or no change) and sets a new expiration time.
SetTimerDeadline process_id timer_name state expiration_time
Argument process_id timer_name state expiration_time
Description
The process instance of the specified timer.
The name of the specified timer.
The specified new state: ON, OFF, or no change.
The new expiration time in DateTimeData format (dd-nnn-yyyy hh:mm:ss, for example, 03-Feb-1993 22:45:12). Applies only to deadline timers.
The
SetTimerDeadline
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
You can use the SetTimerDeadline command to turn any deadline timer on or off, and to set a new expiration time.
Appendix A Conductor Script Commands 303
Conductor Script Commands
SetTimerElapsed
The SetTimerElapsed command sets the specified elapsed timer to the specified state (ON, OFF, or no change) and sets a new elapsed time interval until expiration.
SetTimerElapsed process_id timer_name state time_interval
Argument Description process_id timer_name
The process instance of the specified timer.
The name of the specified timer.
state The specified new state: ON, OFF, or no change.
time_interval The new time interval until expiration, in IntervalData format
(years:months:days:hours:minutes:seconds:milliseconds). Applies only to elapsed timers.
The SetTimerElapsed command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
You can use the
SetTimerElapsed
command to turn any elapsed timer on or off, and to set a new elapsed time interval until expiration.
ShowActivity
The ShowActivity command displays the properties of the specified activity in the current engine.
ShowActivity process_id activity_name
Argument process_id activity_name
Description
The process instance in which the activity was created.
The name of the activity.
The ShowActivity command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
304 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
The
ShowActivity
command displays the following information:
• activity name
• activity ID
• process name
• process ID
• activity state
• activity type
• application description
• list of sessions for which activity is on session activity list, displaying session
ID
• list of process attributes, displaying: attribute name, attribute type, attribute value, attribute lock status
• list of timer links, displaying: timer link name, activity state, timer state, value
You can use the ListActivities Script command to display a list of activities in the engine before selecting the activity to display.
ShowActivityQueue
The
ShowActivityQueue
command displays the contents either of the specified queue or of all queues for a given process definition executed by the current engine.
ShowActivityQueue process_name [queue_name]
Argument process_name queue_name
Description
The name of the process definition in which the queued activity is defined.
The name of the specified activity queue (the same as the name of the queued activity). If not specified, then the contents of all queues for the specified process are displayed.
The ShowActivityQueue command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Appendix A Conductor Script Commands 305
Conductor Script Commands
The
ShowActivityQueue
command displays a list of activities in the queue, if any, or of sessions waiting for a queued activity if no activities are in the queue. For each activity in the queue, the
ShowActivityQueue
command displays the following information: activity name, activity ID, activity state, prioritizing value (value of the queue prioritizing process attribute), and process ID.
ShowConfiguration
The ShowConfiguration command displays contents of the configuration file of the current engine.
ShowConfiguration
The ShowConfiguration command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine. No engine components need be running for this command to work.
ShowEngine
The
ShowEngine command displays the configuration, state, and other properties of the specified engine.
ShowEngine engine_name
Argument Description engine_name The specified engine.
The ShowEngine command is always available. The specified engine need not be running to use the ShowEngine command.
The
ShowEngine
command displays the following properties:
• engine name
• governor run state: TRUE or FALSE
• primary engine unit run state: TRUE or FALSE
• number and names of engine units running
• number and names of database services running
306 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
You can use the
ListEngines
Script command to display a list of engines in the environment before selecting the engine to display.
ShowLogFlags
The ShowLogFlags command displays the log message filters (log flags) for the current component.
ShowLogFlags
The ShowLogFlags command is available only when an engine component is current.
For information on iIS message filters, see
“Messages and Message Filters” on page 212 .
ShowProcess
The ShowProcess command displays the properties of the specified process instance in the current engine.
ShowProcess process_id
Argument process_id
Description
The specified process instance.
The
ShowProcess
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The ShowProcess command displays the following information:
• process name
• process compatibility level
• process ID
• creation time
• list of process attributes, displaying: attribute name, attribute type, attribute value, attribute lock status
Appendix A Conductor Script Commands 307
Conductor Script Commands
• list of activities, displaying activity name, activity ID, process ID, activity state
(as in
ListActivities
Script command)
• list of timers, displaying timer name, process ID, state, type, expiration time and date (as in ListTimers Script command)
• parent activity and engine (for subprocesses)
• list of active attribute accessors
You can use the
ListProcesses
Script command to display a list of process instances in the engine before selecting the process instance to display.
ShowSession
The ShowSession command displays the properties of the specified session in the current engine.
ShowSession session_id
Argument Description session_id The specified session.
The
ShowSession
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The ShowSession command displays the following information:
• session ID
• session name
• client connected: TRUE or FALSE
• session state: ACTIVE or SUSPENDED
• version
• administrative user: TRUE or FALSE
• activity list size
308 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
• user
• user’s roles
• list of active attribute accessors
You can use the ListSessions Script command to display a list of sessions in the engine before selecting the session to display.
ShowStatus
The
ShowStatus
command displays status information for the current engine or any of its individual components.
ShowStatus [ short ]
The
ShowStatus
command is available only when the engine is current or if an engine component is current. Use the
FindEngine
Script command to set the current engine, and, in addition, the
FindGovernor
,
FindDBService
,
FindUnit
, or
FindPrimary
Script command to make the corresponding engine component current.
The properties displayed by the ShowStatus command depend upon whether the engine is current or an engine component is current. If an engine component is current, then using the short option of the ShowStatus command will display an abbreviated set of properties for that component (italicized properties in the lists below are not displayed)
engine:
• engine name
• governor run state: TRUE or FALSE
• primary engine unit run state: TRUE or FALSE
• number and names of engine units running
• number and names of database services running
• number of idle database services
Appendix A Conductor Script Commands 309
Conductor Script Commands
engine unit:
(See also
“primary engine unit:” on page 311
.)
• unit name
• unit state: ONLINE or STANDBY
• shell state: IDLE, TOKEN_REQUESTED (negotiating with partner), or
CONNECTED
• governor channel: OPEN or CLOSED
• partner channel: OPEN or CLOSED
• ping interval
• start time
• host node
database service:
• database service name
• database connection state: CONNECTED or DISCONNECTED
• router channel: OPEN or CLOSED
• ping interval
• start time
• host node
• work units processed
governor:
• governor state: E1, BOTH, E2, or IDLE
• ping interval
• start time
• host node
310 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
primary engine unit:
• unit name
• startup phase (if not ONLINE)
• unit state: ONLINE or STANDBY
• shell state: IDLE, TOKEN_REQUESTED (negotiating with partner), or
CONNECTED
• governor channel: OPEN or CLOSED
• partner channel: OPEN or CLOSED
• ping interval
• start time
• host node
• instruments
The following table shows the instrumentation displayed for the primary engine unit.
Instrument
ActiveSessions
Description
Number of current active sessions
SuspendedSessions
CurrentSessions
TotalSessions
ActiveProcessInstances
TotalProcessInstances Number of process instances since engine startup =
ActiveProcess Instances + number of terminated process instances
ActiveSubProcessInstances Number of current active subprocess instances
TotalSubProcessInstances
PendingActivities
ReadyActivities
Number of current suspended sessions
Number of current sessions = ActiveSessions
+SuspendedSessions
Number of sessions since engine startup =
CurrentSessions + Number of terminated sessions
Number of current active process instances
Number of subprocess instances since engine startup =
ActiveSubProcess Instances + number of terminated subprocess instances
Number of current PENDING activities
Number of current READY activities
Appendix A Conductor Script Commands 311
Conductor Script Commands
Instrument
ActiveActivities
CurrentActivities
CompletedActivities
AbortedActivities
TotalActivities
RunningTimers
StoppedTimers
CurrentTimers
TotalTimers
ReadLocks
WriteLocks
CurrentLocks
TotalLocks
QueuedReadLocks
QueuedWriteLocks
ResponseTime
ActivePages
AllocatedPages
PeakAllocatedPages
TransactionCount
DatabaseName
Description
Number of current ACTIVE activities
Number of current activities = PendingActivities +
ReadyActivities + ActiveActivities
Number of completed activities (terminated) since engine startup
Number of aborted activities (terminated) since engine startup
Number of activities since engine startup =
CurrentActivities +
CompletedActivities + AbortedActivities
Number of current running timers
Number of current stopped timers
Number of current timers = RunningTimers +
StoppedTimers
Number of timers since engine startup = CurrentTimers + number of terminated timers
Number of current read (shared) locks
Number of current write (exclusive) locks
Number of current locks = ReadLocks + WriteLocks
Number of locks since engine startup = CurrentLocks + number of terminated locks
Number of current read (shared) locks queued
Number of current write (exclusive) locks queued
The average time it takes for the engine to complete a request made by a session
The size of the primary engine unit memory heap
The amount of the active memory currently allocated to objects created by the primary engine unit
The amount of allocated memory remaining after the most recent memory reclamation (probably the best measure of active memory utilization)
The number of transactions completed with the engine database since engine startup.
The name of the engine database.
312 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
Instrument
LoginUserName
LoggingState
TransactionCommitTime
DatabaseType
DBServiceRequestTime
Description
The database user (login) name.
The database logging settings: the tables to which the engine is logging state and history information.
The average time it takes the engine to commit a change of state (complete a transaction involving the engine database).
The database management system: ORACLE, SYBASE, etc.
The average time it takes for the database service to complete a request made by the engine.
ShowTimer
The
ShowTimer
command displays the properties of the specified timer.
ShowTimer process_id timer_name
Argument Description
process_id The process instance of the specified timer.
timer_name The specified timer.
The
ShowTimer
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The ShowTimer command displays the following information:
• timer name
• timer state
• process name and ID
• type
• started: TRUE or FALSE
• expiration time and date
You can use the
ShowProcess
Script command to display a list of timers in a specified process instance before selecting the timer to display.
Appendix A Conductor Script Commands 313
Conductor Script Commands
Shutdown
The Shutdown command shuts down the current engine or one of its individual components.
Shutdown
The Shutdown command is available only when the engine is current or if an engine component is current. Use the FindEngine Script command to set the current engine, and, in addition, the FindGovernor , FindDBService , FindUnit , or
FindPrimary Script command to make the corresponding engine component current.
The effect of the
Shutdown
command depends upon whether the engine is current or an engine component is current:
• if engine: shuts down all components of current engine
• if engine component: shuts down the current component
If the Shutdown command results in a primary engine unit being shut down, then all state information in the engine is lost and must be recovered from the engine database when a primary unit comes online.
StartActivity
The
StartActivity
command changes the state of the specified activity from
READY to ACTIVE.
StartActivity process_id activity_name session_id
Argument
process_id
Description
The process instance in which the activity was created.
activity_name The name of the activity.
session_id The session that will perform the ACTIVE activity. Applies only to
Offered and Queued activities.
The
StartActivity
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The StartActivity command does not apply to activities that do not pass through
ACTIVE or READY state, such as First and Last activity.
314 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
In the case of offered and queued activities, which are performed by client applications, the engine will assign the ACTIVE activity to the session specified by the session_id parameter. In the case of Automatic or SubProcess activities, which are not directly performed by client applications, the engine need not assign the
ACTIVE activity to a session.
StartDBService
The StartDBService command starts the specified database service for the current engine.
StartDBService service_name priority
Argument service_name priority
Description
The specified database service.
An integer (positive or negative) that assigns a priority to the specified service. A higher numeric value signifies a higher priority.
A default priority of “1” is used if no priority is specified. See
Configuration: Failover and Load Balancing Combined” on page 35 .
The
StartDBService
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The StartDBService command reads the memory flag setting for database service
specified in the engine configuration file (see “Engine Configuration File” on page 90 and
under “How to Configure a New Engine” on page 95 ).
The
ShowStatus
Script command—or the
FindDBService
command followed by the
ShowStatus
command—can be used to check that the database service has started up properly.
StartEngine
The StartEngine command starts all engine components as specified in the engine configuration file (see
“Engine Configuration File” on page 90
).
StartEngine [newLog] [newState] [newRegistration] [cold]
The StartEngine command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Appendix A Conductor Script Commands 315
Conductor Script Commands
The
StartEngine
command includes a number of start options that create new engine database tables:
Table A-1 StartEngine Command Options
Option Description newLog New history log database tables are created during the primary engine unit startup process. All history log information stored in an existing database is lost.
newState New current state database tables are created during the primary engine unit startup process. All current state information stored in an existing database is lost.
newRegistration New registration database tables are created during the primary engine unit startup process. All registration information stored in an existing database is lost. You must also specify newState when you specify the newRegistration option.
cold All new database tables (log, state, and registration) are created during the primary engine unit startup process. The cold option must always be used the first time an engine is started. If used in subsequent engine starts, however, the cold option will cause deletion of the existing engine database before the creation of the new one. All current state information, history log data, and registration information stored in an existing database is lost.
The newLog , newState , and newRegistration options are independent, except that you cannot create new registration tables without also creating new state tables.
The
ShowStatus
Script command can be used to check that the engine has started up properly.
StartGovernor
The StartGovernor command starts the governor for the current engine.
StartGovernor
The StartGovernor command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
316 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
The
StartGovernor command reads the memory flag setting for governor
specified in the engine configuration file (see “Engine Configuration File” on page 90 and
under “How to Configure a New Engine” on page 95 ).
The ShowStatus Script command—or the FindGovernor command followed by the ShowStatus command—can be used to check that the governor has started up properly.
StartTimer
The
StartTimer
command changes the state of a specified timer from OFF to ON.
StartTimer process_id timer_name
Argument process_id timer_name
Description
The process instance of the specified timer.
The name of the timer to be started.
The
StartTimer
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
The StartTimer command lets you start the specified timer or restart it if it has previously been turned off.
StartUnit
The
StartUnit command starts the specified engine unit for the current engine.
StartUnit unit_name [newLog] [newState] [newRegistration] [cold]
Argument unit_name
Description
The specified engine unit.
The StartUnit command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Appendix A Conductor Script Commands 317
Conductor Script Commands
The
StartUnit
command includes the following start options that create new engine database tables:
Table A-2 StartUnit Command Options
Option Description newLog New history log database tables are created during the primary engine unit startup process. All history log information stored in an existing database is lost.
newState New current state database tables are created during the primary engine unit startup process. All current state information stored in an existing database is lost.
newRegistration New registration database tables are created during the primary engine unit startup process. All registration information stored in an existing database is lost. You must also specify newState when you specify the newRegistration option.
cold All new database tables (log, state, and registration) are created during the primary engine unit startup process. The cold option must always be used the first time an engine is started. If used in subsequent engine starts, however, the cold option causes deletion of the existing engine database before the creation of the new one. All current state information, history log data, and registration information stored in an existing database is lost.
The newLog , newState , and newRegistration options are independent, except that you cannot create new registration tables without also creating new state tables.
The
StartUnit command reads the memory flag setting for the engine unit
specified in the engine configuration file (see “Engine Configuration File” on page 90 and
under “How to Configure a New Engine” on page 95 ).
The ShowStatus Script command— or the FindUnit command followed by the
ShowStatus command—can be used to check that the engine unit has started up properly.
318 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
StopTimer
The StopTimer command changes the state of the specified timer from ON to OFF.
StopTimer process_id timer_name
Argument Description process_id The process instance of the specified timer.
timer_name The name of the timer to be reset.
The StopTimer command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
StopTimer command lets you stop the specified timer. The timer can be subsequently restarted with the
StartTimer
Script command.
SuspendAllSessions
The SuspendAllSessions command suspends all active sessions in the current engine.
SuspendAllSessions
The SuspendAllSessions command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
SuspendAllSessions
command places all ACTIVE sessions in SUSPENDED state, making them dormant: the engine cannot assign new activities to suspended sessions or post events to them.
Automatic reconnect by the client application does not take place if sessions are suspended with the SuspendSession command. A subsequent explicit client request to open each session can restore the session to ACTIVE state or create a new session, depending on the value of the reconnectAction property set when each session was originally opened.
The engine posts a SessionSuspended event on each session before it is suspended, so that the client applications can take appropriate action. The effect of suspending a session on any ACTIVE activities depends on the suspendAction property set by each client application when accepting each activity.
Appendix A Conductor Script Commands 319
Conductor Script Commands
SuspendSession
The SuspendSession command suspends the specified active session, or sessions, in the current engine.
SuspendSession session_id [session_id…]
Argument Description session_id The specified active session. (A list of up to ten session_ids separated by spaces is supported.)
The SuspendSession command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
SuspendSession
command places an ACTIVE session in SUSPENDED state.
This means that the session is now dormant: the engine cannot assign new activities to a suspended session or post events to it.
Automatic reconnect by the client application does not take place if a session is suspended using the SuspendSession command. A subsequent explicit client request to open the session can restore it to ACTIVE state or create a new session, depending on the value of the reconnectAction property set when the session was first opened.
The engine posts a SessionSuspended event on the session before it is suspended, so that the client application can take appropriate action. The effect of suspending a session on any ACTIVE activities depends on the suspendAction property set by the client application when accepting each activity.
TerminateAllSessions
The TerminateAllSessions command terminates all sessions in the current engine.
TerminateAllSessions
The TerminateAllSessions command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
TerminateAllSessions command ends all sessions and deletes them from the engine and the engine’s state database table.
320 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
The engine posts a SessionTerminated event on each session before it is terminated, so that the respective client applications can take appropriate action. The effect of terminating a session on any ACTIVE activities is to place the activities back in
READY state.
TerminateSession
The TerminateSession command terminates the specified session in the current engine.
TerminateSession session_id [session_id…]
Argument Description session_id The specified session. (A list of up to ten session_ids separated by spaces is supported.)
The TerminateSession command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
The
TerminateSession command ends the session and deletes it from the engine and the engine’s state database table.
The engine posts a SessionTerminated event on the session before it is terminated, so that the client application can take appropriate action. The effect of terminating a session on any ACTIVE activities is to place the activities back in a READY state.
Uninstall
The
Uninstall command deletes an iIS distribution of the specified name and compatibility level from the environment repository.
Uninstall name compatibility_level
Argument Description name The name of the library distribution to be deleted from the environment repository.
compatibility_level The compatibility level of the distribution to be deleted.
Appendix A Conductor Script Commands 321
Conductor Script Commands
The
Uninstall
command is always available.
The Uninstall command is normally performed to clean up the environment repository after unregistering an iIS distribution from all engines in an environment.
UnRegisterAlias
The
UnRegisterAlias command unregisters the specified subprocess alias from the current engine’s registration database. For more information on aliases, see
UnRegisterAlias alias_name t
Argument alias_name
Description
The name of the alias (same as the process name).
The UnRegisterAlias command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Use the
ListRegistrations
Script command to display a list of components registered with the current engine (you can filter the list for aliases). The
UnRegisterAlias
command will remove the alias from the registration table, however it should be replaced by a new alias if the location of a subprocess is required by a process executing on the current engine.
UnRegisterAssignmentRules
The UnRegisterAssignmentRules command deletes all assignment rules (or just the specified rule) in the specified assignment rule dictionary from the current engine’s registration database.
UnRegisterAssignmentRules dictionary_name [rule_name]
Argument dictionary_name
Description
The name of the assignment rule dictionary to be unregistered.
322 iPlanet Integration Server • Process System Guide • August 2001
Argument rule_name
Conductor Script Commands
Description
The name of the assignment rule to be unregistered. If not specified, then all assignment rules in the specified dictionary will be unregistered.
The UnRegisterAssignmentRules command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
Use the
ListRegistrations
Script command to display a list of components registered with the current engine (you can filter the list for assignment rule dictionaries). The
UnRegisterAssignmentRules
command removes the specified assignment rule or the entire assignment rule dictionary from the registration table, preventing subsequent use of any of the assignment rules in process execution on the current engine.
UnRegisterProcessDefinition
The UnRegisterProcessDefinition command deletes the specified process definition from the current engine’s registration database.
UnRegisterProcessDefinition process_name
Argument Description process_name The name of the registered process definition.
The
UnRegisterProcessDefinition
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
Use the ListRegistrations Script command to display a list of components registered with the current engine. You can filter the list for process definitions.
The UnRegisterProcessDefinition command removes the specified process definition from the registration table but will have no effect on currently running process instances. It prevents subsequent creation of instances of the process definition on the current engine.
Appendix A Conductor Script Commands 323
Conductor Script Commands
UnRegisterUserProfile
The UnRegisterUserProfile command deletes the specified user profile from the current engine’s registration database.
UnRegisterUserProfile user_profile_name
Argument user_profile_name
Description
The name of the registered user profile.
The
UnRegisterUserProfile
command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
Use the ListRegistrations Script command to display a list of components registered with the current engine. You can filter the list for user profiles. The
UnRegisterUserProfile command removes the specified user profile from the registration table.
WaitForStartup
The
WaitForStartup
command waits a specified timeout period for a specified engine unit to start up, and prints an error message if the engine unit does not start within the specified time.
WaitForStartup unit_name timeout
Argument Description unit_name The specified engine unit.
timeout A timeout period (in seconds) within which the specified engine unit must start up, or an error message is written.
324 iPlanet Integration Server • Process System Guide • August 2001
Conductor Script Commands
The
WaitForStartup command is available only when an engine is current, so you must first use the
FindEngine
Script command to set the current engine.
In a script, the WaitForStartup command is used after a StartUnit Script command. The WaitForStartup command causes the script to pause until the specified engine unit successfully starts up before continuing with subsequent
Script commands. If the engine unit does not start up within the specified time, an error message is generated and the script aborts.
Appendix A Conductor Script Commands 325
Conductor Script Commands
326 iPlanet Integration Server • Process System Guide • August 2001
Appendix B
Engine Database Schema
This appendix documents the engine database schema. It lists the database tables and the specification of each, according to the following categories:
• current state tables
• registration tables
• history log tables
The tables are grouped first by category, and then alphabetically within each category. For an alphabetical listing of all tables, see
Database Tables by Category
The tables comprising the engine database are listed in the following table. They are grouped into the following categories: current state, registration, and history log tables.
Current State Tables Registration Tables History Log Tables
WFHProcess
WFHRegistration
WFHAlias
WFHRegistrationLog
WFHAliasLog
WFHProcessLog*
WFHProcessStateLog*
WFHProcAttributes
WFHLocks
WFHProcAttribLog*
WFHAttribLockLog*
* corresponds to History log configuration options. See “How to Configure a New Engine” on page 95 .
327
Database Tables by Category
Current State Tables
WFHProcParameters
WFHTerminatedProcs
WFHTermProcParas
WFHActivity
Registration Tables History Log Tables
WFHActivityLog*
WFHActStateLog*
WFHQueuedActivity
WFHRoleBasedAct
WFHActivityTokens
WFHActivityUsers
WFHAssignment
WFHSession
WFHSessionRole
WFHSessAttributes
WFHRetryInfo
WFHTimer
WFHSessionLog*
WFHTimerLog*
WFHTimerStateLog*
WFHActiveTimer
WFHComplexRule
WFHControl
WFHRecoveryHelp
WFHColdStart WFHColdStartLog
WFHPerformanceLog
WFHAlarmLog
* corresponds to History log configuration options. See “How to Configure a New Engine” on page 95 .
328 iPlanet Integration Server • Process System Guide • August 2001
Alphabetical Listing of Tables
Alphabetical Listing of Tables
The following is an alphabetical list of all tables created in the engine database, with a page reference to details about each.
Table B-1 Engine Database Tables
Database Table See…
Description
Active timers that are not in memory.
Activity instances that are current in the engine.
Log of activity instances (both current and past) in the system.
Activity token counts—number of times the activity has completed—that are current in the system.
Activity link information: who has completed some activity. A row is held representing each activity that is listed as the activity link in some other activity.
Log of state changes in activity instances in the engine.
A log of all alarms generated on this engine, recorded whenever history logging is turned on.
Aliases currently registered with the engine.
A log of aliases registered with the engine.
Used by the engine to track the stack of assignment rules generated by ConsultActivity and DelegateActivity method calls from client applications.
Log of access obtained on all instances of process attributes.
System maintained table used by the engine before performing a cold start.
Always contains one row showing the last time the engine was cold started (thus dropping and re-creating all registration, state, and log tables).
Used by the engine to track activities that contain complex assignment rules (assignment rules with custom Evaluate methods).
Appendix B Engine Database Schema 329
Alphabetical Listing of Tables
Table B-1 Engine Database Tables (Continued)
Database Table See… Description
System maintained table of sequence values for producing unique IDs for process, session, and timer instances.
The type of access held on all instances of process attributes.
Provides performance statistics for the engine.
Average time measurements are expressed in milliseconds.
Log of value changes to process attributes.
Current values of process attributes within all current process instances.
All current process instances within the engine.
Log of process instances created in this engine.
Log of state changes to process instances in this engine.
For a synchronous subprocess, the list of output parameters it must supply to its parent.
Managed by the engine to maintain queued activities not in memory.
Internal use only.
Currently registered iIS plans.
Log of registrations with the engine.
Internal use only. Managed by the engine to ensure consistency between engine actions and messages to client applications.
Internal use only. Managed by the engine to manage role-based activities.
User profile attributes associated with a session.
Currently active and suspended client sessions with the engine.
Log of current and past client session.
330 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-1 Engine Database Tables (Continued)
Database Table See… Description
Current client sessions and their roles. If a session has multiple roles, this table has a separate row for each role.
Internal use only. Managed by the engine to track aborted synchronous subprocesses.
Internal use only. Managed by the engine to track output parameters from aborted synchronous subprocesses.
Timer instances currently instantiated in the engine.
Log of timer instances that have been instantiated in the engine.
Log of the state of timer instances for the engine.
Database Schema Reference
This section provides an annotated description of all the tables created and maintained by an iIS process engine. The iIS process engine automatically creates these tables when the engine is cold started and maintain their contents during normal operations. You can use the information provided here to write queries against the tables for management information on current and past process instances. However, you should avoid altering the rows in the tables (with the exception of periodically flushing history tables of rows that are no longer needed).
Some tables are for internal use only, and are unlikely to be useful for any management queries. The documentation on these tables is limited.
The data type description for each entry in a table is based on the representation used in Oracle databases. The actual data type may differ, depending on the database vendor you are using.
NOTE The schema presented here may differ from the schema for previous versions of iIS. Also, the schema is subject to further change in future versions.
Appendix B Engine Database Schema 331
Database Schema Reference
Current State Tables
The following is an alphabetical list of all current state tables in the engine database. Indexes to tables are indicated by a checkmark (✔) in the Index column.
In some cases, a table has an alternate index, indicated by a bullet (●).
For a description of each of these tables, refer to
Table B-2 WFHActiveTimer
Name Index Null?
ID ✔ NOT
NULL
Type
NUMBER(38)
PROCESSID
TIMETOALARM
✔ NOT
NULL
NUMBER(38)
DATE
Description
Identifier for the timer instance within the process instance designated by
PROCESSID.
Unique identifier for the process instance in which this active timer occurs.
Date time stamp indicating when the timer is expected to expire.
Table B-3 WFHActivity
Name Index Null?
PROCESSID ✔ NOT
NULL
ROOTPROCID
Type
NUMBER(38)
NUMBER(38)
Description
Unique identifier for the process instance in which this activity instance occurs.
Identifier for the process instance on this engine that originally invoked this process. For a process instance that is not running as a subprocess, this is the same as PROCESSID. For a subprocess, this is the PROCESSID of the parent process instance, or its parent, or its parent; up to the original initiating process instance.
332 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-3 WFHActivity (Continued)
Name Index Null?
TYPE
ID
STATE
PREVSTATE
CREATETIME
SESSIONID
✔ NOT
NULL
●
Type
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
DATE
NUMBER(38)
Description
Type of activity:
1 – First activity
2 – Last activity
3 – Offered activity
4 – Subprocess activity
5 – Automatic activity
6 – Queued activity
7 – Junction activity
Note: These constant values are internal to the engine only. You should avoid their use if possible.
Unique identifier for this activity instance within the process instance in which it occurs.
Activity state:
10 – WFActivity.PENDING
20 – WFActivity.READY
25 – WFActivity.PREPARE_ACTIVE
30 – WFActivity.ACTIVE
35 – WFActivity.PREPARE_COMPLETE
40 – WFActivity.COMPLETED
45 – WFActivity.PREPARE_ABORT
50 – WFActivity.ABORTED
The state the activity was in immediately prior to the current state. See the values for STATE above.
Time that the activity instance was created.
For an ACTIVE activity, the ID of the session that owns the activity. This column links to column
WFHSESSION.ID
Appendix B Engine Database Schema 333
Database Schema Reference
Table B-3 WFHActivity (Continued)
Name Index Null?
ACTNAME
ABORTRACTION
WUSER
OTHERINFO
CURASSIGNRULE
NEXTASSIGNID
FIFOORDER
SUSPENDACTION
Type Description
VARCHAR2(64) The name of the activity in the process definition.
NUMBER(38) Abort routing information. Internal use only.
VARCHAR2(64) The “LinkedUser” information passed into this activity by its activity link. If there is no activity link, value is
“<NO_LINKED_USER>”
VARCHAR2(64) The “OtherInfo” information passed into this activity by its activity link. If there is no activity link, value is
“<NO_OTHERINFO>”
VARCHAR2(64) This column is used internally by the engine to track dynamic assignment rules during a ConsultActivity or
DelegateActivity method call from a client application.
NUMBER(38) This column is used internally by the engine to track dynamic assignment rules during a ConsultActivity or
DelegateActivity method call from a client application.
NUMBER(38)
NUMBER(38)
For a queued activity with the queue prioritized by ‘First In First Out’ (the default), a system-assigned sequence value for placement of this activity in the queue.
Actions to take when the activity is suspended:
700 – WFActivity.RETAIN
701 – WFActivity.REMOVE
PRIORITY
READYCOUNT
NULL
NOT
NULL
NOT
NULL
NUMBER(38)
NUMBER(38)
Internal use only.
Internal use only.
334 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-4 WFHActivityTokens
Name Index Null?
PROCESSID
ACTIVITYID
✔ NOT
NULL
✔ NOT
NULL
ACTIVITYNAME
TOKCOUNTER
Type Description
NUMBER(38) Unique identifier for the process instance in which this activity instance occurs.
NUMBER(38)
VARCHAR2(64) The name of an activity that is an immediate predecessor of the activity instance identified by the ACTIVITYID in this row.
NUMBER(38)
Unique identifier for a pending activity instance within the process instance in which it occurs.
Value of the attribute
_COUNT<ActivityName>, where
<ActivityName> is the same as
ACTIVITYNAME in this row.
Table B-5 WFHActivityUsers
Name Index Null?
PROCESSID
ACTIVITYNAME
✔ NOT
NULL
✔ NOT
NULL
WUSER
OTHERINFO
Type Description
NUMBER(38) Unique identifier for the process instance in which this activity instance occurs.
VARCHAR2(64) The name of the activity in the process definition.
VARCHAR2(64) The name of the user who completed the last instance of this activity.
VARCHAR2(64) The otherInfo of the user who completed the last instance of this activity.
Appendix B Engine Database Schema 335
Database Schema Reference
Table B-6 WFHAssignment
Name Index Null?
PROCESSID
ACTIVITYID
✔ NOT
NULL
✔ NOT
NULL
ID
LINKEDUSER
OTHERINFO
ASSIGNMENTRULE
✔
Type
NUMBER(38)
NUMBER(38)
Description
Unique identifier for the process instance in which this activity instance occurs.
Identifier for the activity instance in the process instance designated by
PROCESSID.
Identifier for the assignment rule.
NUMBER(38)
VARCHAR2(64) The “LinkedUser” information passed into this activity by its activity link. If there is no activity link, value is
“<NO_LINKED_USER>”
VARCHAR2(64) The “OtherInfo” information passed into this activity by its activity link. If there is no activity link, value is
“<NO_OTHERINFO>”
VARCHAR2(64) The name of an assignment rule generated by a call to ConsultActivity or
DelegateActivity from a client application.
Table B-7 WFHColdStart
Name Index Null?
SEQID
VERNUM
LOGVER
REGVER
Type
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
STATEVER NUMBER(38)
Description
Internal use only.
Schema version of the engine database.
Version of the database log table.
Version of the database registration table.
Version of the database state table.
336 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-8 WFHComplexRule
Name Index Null?
PROCESSID ✔
Type
NUMBER(38)
ACTIVITYID ✔ NUMBER(38)
Description
Unique identifier for the process instance in which this activity instance occurs.
Identifier for the activity instance in the process instance designated by
PROCESSID.
Table B-9 WFHControl
Name
NEXTSESSIONID
Index Null?
Type
NUMBER(38)
NEXTPROCESSID
NEXTTIMERID
HISTORYDETAIL
NUMBER(38)
NUMBER(38)
NUMBER(38)
Description
System maintained sequence for session
ID values.
System maintained sequence for process
ID values.
System maintained sequence for timer
ID values.
Internal use only.
Table B-10 WFHLocks
Name
PROCESSID
ATTNAME
ACTIVITYID
SESSIONID
Index Null?
✔
✔
Type Description
NUMBER(38) Unique identifier for the process instance in which this process attribute occurs.
VARCHAR2(64) Name of the process attribute.
NUMBER(38)
NUMBER(38)
If the access to the process attribute is associated with an activity, the unique identifier for this activity instance.
If the access to the process attribute is associated with a user session, the unique identifier for this session.
Appendix B Engine Database Schema 337
Database Schema Reference
Table B-10 WFHLocks (Continued)
Name Index Null?
LOCKTYPE
ACCESSORID ✔
Type
NUMBER(38)
NUMBER(38)
Description
Type of access to the process attribute:
1 – WFAttributeAccessor.READ
2 – WFAttributeAccessor.READQ
3 – WFAttributeAccessor.WRITE
4 – WFAttributeAccessor.WRITEQ
5 – WFAttributeAccessor.NO_LOCK
Unique identifier for the attribute accessor instance within the process instance.
Table B-11 WFHProcAttributes
Name Index Null?
PROCESSID NOT
NULL
ATTNAME
ATTTYPE
ATTSEGMENTID
ATTSEGLENGTH
ATTVALUE
✔
Type Description
NUMBER(38) Unique identifier for the process instance in which this process attribute occurs.
VARCHAR2(64) Name of the process attribute.
NUMBER(38) Type of the attribute:
1 – IntegerData
2 – TextData
3 – BooleanData
4 – DateTimeData
NUMBER(38)
5 – DoubleData
6 – IntervalData
7 – DecimalData
8– XMLData
Internal use only.
NUMBER(38) Internal use only.
VARCHAR2(255) The value of the attribute, in readable character form.
338 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-12 WFHProcess
Name
ID
Index Null?
✔ NOT
NULL
TYPE
STATE
SUBMITTIME
PARENTACTIVITY
PARENTPROCESSID
ROOTPROCESSID
PARENTENVIRONMENT
PARENTENGINE
COLDSEQID
Type Description
NUMBER(38)
NUMBER(38)
NUMBER(38)
Unique identifier for the process instance in this engine.
Type of process (means of process creation):
1 – Process
2 – Subprocess
State of the process instance:
405 – WFProcess.PREPARE_CREATE
DATE
NUMBER(38)
NUMBER(38)
NUMBER(38)
410 – WFProcess.CREATED
420 – WFProcess.ACTIVE
430 – WFProcess.COMPLETED
435 – WFProcess.PREPARE_ABORT
440 – WFProcess.ABORTED
Date and time the process instance was begun.
For a subprocess, the activity ID of the subprocess activity instance in the parent process that invoked this process.
For a subprocess, the process ID for the process instance that started this process instance.
For a subprocess, the process ID for the process instance that ultimately started this process (the parent of the parent of the parent … of this process, up to the original process that is not a subprocess).
VARCHAR2(64) For a subprocess, the environment of the engine of the process instance that started this process instance.
VARCHAR2(64) For a subprocess, the name of the engine of the process instance that started this process.
NUMBER(38) Internal use only.
Appendix B Engine Database Schema 339
Database Schema Reference
Table B-12 WFHProcess (Continued)
Name
NEXTACTIVITYID
INTERNALNAME
PROCNAME
RECOVERYLEVEL
PARENTACTNAME
USERID
PATTNAME
COMPLEVEL
MSTATUS
Index Null?
NOT
NULL
Type Description
NUMBER(38)
VARCHAR2(138) Internal use only.
VARCHAR2(64) The name of the process definition of which this running process is an instance.
NUMBER(38)
Sequence for the next activity instance within this process instance.
The recovery level designated for this process:
0 – WFProcess.RCVR_NORMAL
501 – WFProcess.RCVR_ONLY
502 – WFProcess.RCVR_NONE
503 – WFProcess.RCVR_FULL
504 – WFProcess.RCVR_PARENT
VARCHAR2(64) For a subprocess, the name of the parent activity that invoked the subprocess.
VARCHAR2(64) The user who started the process.
VARCHAR2(64) The name of the primary attribute of the process.
NUMBER(38) Compatibility level for the process.
NOT
NULL
NOT
NULL
NUMBER(38) Internal use only.
340 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-13 WFHProcParameters
Name Index Null?
PROCESSID ✔ NOT
NULL
ATTNAME
Type Description
NUMBER(38) The PROCESSID of a synchronous subprocess that has an output parameter.
VARCHAR2(64) The name of a process attribute that must be returned to the calling process
(an output parameter).
Table B-14 WFHQueuedActivity
Name Index Null?
ID
PROCESSID
FIFOORDER
PRIORITY
QUEUENAME
✔
NOT
NULL
● NOT
NULL
NOT
NULL
Type
NUMBER(38)
NUMBER(38)
NUMBER(38)
Description
Identifier for the activity being queued.
Unique identifier for the process instance containing the queued activity.
The placement of the activity in the queue, based on FIFO order (first in, first out).
The priority of the queued activity.
✔ NOT
NULL
✔ NOT
NULL
NUMBER(38)
VARCHAR2(129) The name of the activity queue in which the activity is placed.
Table B-15 WFHRecoveryHelp
Name Index Null?
PROCESSID
ACTIVITYID
NOT
NULL
NOT
NULL
Type
NUMBER(38)
NUMBER(38)
Description
Unique identifier for a process instance in the engine.
Identifier for an activity instance in the process instance designated by
PROCESSID.
Appendix B Engine Database Schema 341
Database Schema Reference
Table B-16 WFHRetryInfo
Name Index Null?
GROUPID ✔ NOT
NULL
SEQNUMBER NOT
NULL
PROCESSID
ACTIVITYID
REQSTATUS
ACTIONFLAG
Type
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
Description
Identifier for the session between the engine and client.
Identifier for the retry attempt.
Unique identifier for a process instance in the engine.
Identifier for an activity instance in the process instance designated by
PROCESSID.
Internal use only.
Internal use only.
Table B-17 WFHRoleBasedAct
Name Index Null?
PROCESSID
ID
ROLENAME
STATE
● NOT
NULL
✔ NOT
NULL
✔
NOT
NULL
Type Description
NUMBER(38) Unique identifier for a process instance in the engine.
NUMBER(38) Identifier for the role-based activity instance in the process instance designated by PROCESSID.
VARCHAR2(64) The user role name.
NUMBER(38) Internal use only.
342 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-18 WFHSessAttributes
Name Index Null?
SESSIONID ✔ NOT
NULL
ATTNAME
ATTTYPE
ATTSEGMENTID
ATTSEGLENGTH
NOT
NULL
NOT
NULL
NOT
NULL
NOT
NULL
ATTVALUE
SETNUMBER
NOT
NULL
✔ NOT
NULL
Type Description
NUMBER(38) Identifier for the session between the engine and client application.
VARCHAR2(64) Name of a process attribute in the session.
NUMBER(38) The type of the process attribute.
NUMBER(38)
NUMBER(38)
Internal use only.
Internal use only.
VARCHAR2(255) The value of the attribute (in text format).
NUMBER(38) Internal use only.
Table B-19 WFHSession
Name
ID
Index Null?
✔ NOT
NULL
SESSNAME
USERNAME
PROFILENAME
STATE
SESSMODE
SESSTXID
OTHERINFO
Type
NUMBER(38)
Description
Unique identifier for this client session.
VARCHAR2(64) The session name.
VARCHAR2(64) The user name of the user on the session.
VARCHAR2(64) The profile name of the user on the session.
NUMBER(38) The state of the session:
210 – WFSession.ACTIVE
220 – WFSession.SUSPENDED
NUMBER(38) Internal use only.
VARCHAR2(255) The transaction ID, used only in iIS two-phase commit operations.
VARCHAR2(64) The otherInfo attribute associated with a user profile.
Appendix B Engine Database Schema 343
Database Schema Reference
Table B-20 WFHSessionRole
Name Index Null?
SESSIONID NOT
NULL
ROLENAME ●
Type Description
NUMBER(38) Unique identifier for the client session.
Joins to WFHSESSION.ID.
VARCHAR2(64) A role held by the session.
Table B-21 WFHTerminatedProcs
Name Index Null?
COMBINEDID ✔ NOT
NULL
PROCESSID
Type Description
VARCHAR2(158) Internal use only.
ACTIVITYID
ENVIRONMENT
ENGINE
COLDSEQID
COMPLETIONCODE
USERNAME
OTHERINFO
NUMBER(38)
NUMBER(38)
Unique identifier for a process instance in the engine.
Identifier for an activity instance within the process instance designated by
PROCESSID.
VARCHAR2(64) The name of the environment the engine is running in.
VARCHAR2(64) The name of the engine.
NUMBER(38) Internal use only.
NUMBER(38) Indicates the completion state of the process:
440 – Aborted
430 – Completed
VARCHAR2(64) The user name for the user that started the process.
VARCHAR2(64) The otherInfo attribute associated with a user profile.
344 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-22 WFHTermProcParas
Name Index Null?
COMBINEDID ✔ NOT
NULL
ATTNAME
ATTTYPE
ATTSEGMENTID
ATTSEGLENGTH
ATTVALUE
Type Description
VARCHAR2(158) Internal use only.
VARCHAR2(64) The name of the attribute that must be returned to the calling process (an output parameter).
NUMBER(38) Attribute type.
NUMBER(38)
NUMBER(38)
Internal use only.
Internal use only.
VARCHAR2(255) The value of the attribute (in text format)
Table B-23 WFHTimer
Name
ID
PROCESSID
TIMERNAME
STATE
RELATIVETIME
Index Null?
✔ NOT
NULL
✔ NOT
NULL
Type Description
NUMBER(38)
NUMBER(38)
Unique identifier for the timer instance within this engine.
Unique identifier for the process instance in which this timer instance occurs.
VARCHAR2(64) Name of the timer in the process definition.
NUMBER(38) State of the timer:
820 – WFTimer.OFF
830 – WFTimer.ON
VARCHAR2(32) For an elapsed timer, the defined duration of time set for the timer, expressed in character form.
For a deadline timer, the defined expiration time set for the timer, expressed in character form.
Appendix B Engine Database Schema 345
Database Schema Reference
Table B-23 WFHTimer (Continued)
Name Index Null?
CURRELATIVETIME
TIMETOALARM
TYPE
Type Description
VARCHAR2(32) For a paused elapsed timer, the duration remaining should the timer be turned on again without reset, expressed in character form.
DATE
For a paused deadline timer, the
“remembered” expiration time should the timer be turned on again without reset, expressed in character form.
For a running timer, the time when it will expire.
NUMBER(38) Type of timer:
1 – WFTimer.ELAPSED
2 – WFTimer.DEADLINE
Registration Tables
This section contains an alphabetical list of all registration tables in the engine database. For a description of each of these tables, refer to
.
Table B-24 WFHAlias
Name
ALIAS
PROCESS
ENGINE
ENVIRONMENT
Index Null?
✔ NOT
NULL
Type Description
VARCHAR2(64) Name of an alias registered on this engine.
VARCHAR2(64) Name of the process definition which the alias represents (same as the alias name).
VARCHAR2(64) Engine where the actual process definition resides.
VARCHAR2(64) Environment of the engine where the actual process definition resides.
346 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-25 WFHRegistration
Name Index Null?
APPLICATIONID
COMPATIBILITYLEVEL
LIBRARYNAME
LOADOPTIONS
PROJECTNAME
REGISTRATIONNAME
TYPE
✔ NOT
NULL
✔ NOT
NULL
✔ NOT
NULL
✔ NOT
NULL
Type Description
VARCHAR2(32) Name of the installed application for this iIS plan.
NUMBER(38) Compatibility level of the installed library of this iIS plan.
VARCHAR2(64) Name of the installed library for this iIS plan.
NUMBER(38) Internal use only.
VARCHAR2(67) Name of the generated TOOL project of the compiled iIS plan.
VARCHAR2(64) Name of the source iIS plan from which the iIS component is derived.
NUMBER(38) Type of iIS plan:
151-Process Definition
152-Validation
153-Assignment Rule
154-User Profile
WUSAGE NUMBER(38)
CREATETIME DATE
OBSOLETE ✔ NOT
NULL
NUMBER(38)
Date and time of registration.
Internal use only.
History Log Tables
The following is an alphabetical list of all history log tables in the engine database.
lists the possible values for the State field present in many of the history log tables.
For a description of each of these tables, refer to
Appendix B Engine Database Schema 347
Database Schema Reference
Table B-26 WFHActivityLog
Name Index Null?
ID
ACTNAME
CREATETIME
PROCESSID
LOGTIME
Type Description
NUMBER(38)
VARCHAR2(64) The name of the activity in the process definition.
DATE Time that the activity instance was created.
NUMBER(38)
Unique identifier for this activity instance within the process instance in which it occurs.
DATE
Unique identifier for the process instance in which this activity instance occurs.
Time of this logging.
Table B-27 WFHActStateLog
Name Index Null?
ID
PROCESSID
STATE
PREVSTATE
Type
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
Description
Unique identifier for this activity instance within the process instance in which it occurs.
Unique identifier for the process instance in which this activity instance occurs.
Activity state:
10 – WFActivity.PENDING
20 – WFActivity.READY
25 – WFActivity.PREPARE_ACTIVE
30 – WFActivity.ACTIVE
35 – WFActivity.PREPARE_COMPLETE
40 – WFActivity.COMPLETED
45 – WFActivity.PREPARE_ABORT
50 – WFActivity.ABORTED
Immediately previous state of this activity. Values are the same as in STATE above.
348 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-27 WFHActStateLog (Continued)
Name Index Null?
SESSIONID
Type
NUMBER(38)
LOGTIME DATE
Description
ID of the session that owns this activity
(if the activity is ACTIVE).
Time of this logging.
Table B-28 WFHAlarmLog
Name Index Null?
ALARMTYPE
DETAILS
LOGTIME
Type Description
VARCHAR2(64) The type of the alarm.
VARCHAR2(255) The text of the alarm.
DATE Time of this logging.
Table B-29 WFHAliasLog
Name Index Null?
ALIAS
PROCESS
ENGINE
ENVIRONMENT
STATE
LOGTIME
Type Description
VARCHAR2(64) Name of an alias registered (or now unregistered) on this engine.
VARCHAR2(64) Name of the process definition which the alias represents (same as the alias name).
VARCHAR2(64) Engine where the actual process definition resides.
VARCHAR2(64) Environment of the engine where the actual process definition resides.
NUMBER(38) State of this alias registration:
1 – Registered
DATE
-1 – Unregistered
Time of this logging.
Appendix B Engine Database Schema 349
Database Schema Reference
Table B-30 WFHAttribLockLog
Name Index Null?
PROCESSID
ACTIVITYID
SESSIONID
ACCESSORID
ATTNAME
LOCKTYPE
STATE
LOGTIME
Type Description
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
DATE
Unique identifier for the process instance in which this process attribute occurs.
If the access to the process attribute is associated with an activity, the unique identifier for this activity instance.
If the access to the process attribute is associated with a user session, the unique identifier for this session.
NUMBER(38) Unique identifier for this attribute accessor instance within this process instance.
VARCHAR2(64) Name of the process attribute.
NUMBER(38) Type of access to the process attribute:
0 – Not applicable (used internally)
1 – WFAttributeAccessor.READ
2 – WFAttributeAccessor.READQ
3 – WFAttributeAccessor.WRITE
4 – WFAttributeAccessor.WRITEQ
5 – WFAttributeAccessor.NO_LOCK
Internal use only.
Time of this logging.
Table B-31 WFHColdStartLog
Name Index Null?
SEQID
STARTTIME
Type
NUMBER(38)
DATE
PROCATTSIZE
SESSATTSIZE
NUMBER(38)
NUMBER(38)
Description
Internal use only.
Date and time this engine was last cold started.
Internal use only.
Internal use only.
350 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-32 WFHPerformanceLog
Name Index Null?
SAMPLETIME
RESPONSETIME
SWAPINTIME
SWAPOUTTIME
TXCOMMITTIME
NOT
NULL
NOT
NULL
NOT
NULL
NOT
NULL
NOT
NULL
Type
DATE
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
APPCPUTIME
GCCPUTIME
ACTIVESESSION
ACTIVEPROCESS
ACTIVESUBPROCESS
PENDINGACTIVITY
READYACTIVITY
RUNNINGTIMER
STOPPEDTIMER
NULL
NOT
NUL
NOT
NUL
NOT
NULL
NUMBER(38)
NUMBER(38)
NUMBER(38)
NULL
NOT
NULL
NOT
NULL
NOT
NULL
NOT
NULL
NUMBER(38)
NUMBER(38)
NUMBER(38)
NUMBER(38)
NULL
NOT
NULL
NOT
NULL
NUMBER(38)
NUMBER(38)
Description
Date time stamp for the sample.
Average engine response time to requests by a client application.
Average process swap in time.
Average process swap out time.
Average engine transaction commit time.
Average DB service acquire time.
Engine CPU time.
Engine garbage collection time.
The number of active sessions.
The number of suspended sessions.
The number of active processes.
The number of active subprocesses.
The number of pending activities.
The number of ready activities.
The number of active activities.
The number of running timers.
The number of stopped timers.
Appendix B Engine Database Schema 351
Database Schema Reference
Table B-32 WFHPerformanceLog (Continued)
Name Index Null?
Type
ACTIVEPAGE NUMBER(38)
ALLOCATEPAGE
NOT
NULL
NOT
NULL
NUMBER(38)
Description
The number of active memory pages for the engine.
The number of allocated memory pages for the engine.
Table B-33 WFHProcAttribLog
Name Index Null?
PROCESSID
ATTNAME
ATTTYPE
ATTSEGMENTID
ATTSEGLENGTH
ATTVALUE
STATE
LOGTIME
Type Description
NUMBER(38) Unique identifier for the process instance in which this process attribute occurs.
VARCHAR2(64) Name of the process attribute.
NUMBER(38) Type of the attribute:
1 – IntegerData
2 – TextData
3 – BooleanData
4 – DateTimeData
5 – DoubleData
6 – IntervalData
7 – DecimalData
NUMBER(38)
8 – XmlData
Internal use only.
NUMBER(38) Internal use only.
VARCHAR2(255) New value of the attribute.
NUMBER(38) New state of the process attribute:
1 – Instantiation
DATE
0 – Value change
-1 – Uninstantiation
Time of this logging.
352 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-34 WFHProcessLog
Name Index Null?
ID
PROCNAME
SUBMITTIME
PARENTACTIVITY
PARENTPROCID
ROOTPROCID
LOGTIME
PARENTENVIRONMENT
PARENTENGINE
Type Description
NUMBER(38) Unique identifier for the process instance in this engine.
VARCHAR2(64) The name of the process definition of which this process is an instance.
DATE Date and time the process instance was begun.
NUMBER(38)
NUMBER(38)
For a subprocess, the activity ID of the subprocess activity instance in the parent process that invoked this process. The value is 0 if this is not a subprocess.
For a subprocess, the process ID for the process instance that started this process instance. The value is 0 if this is not a subprocess.
NUMBER(38) For a subprocess, the process ID for the process instance that ultimately started this process (the parent of the parent of the parent … of this process, up to the original process that is not a subprocess).
The value is 0 if this is not a subprocess.
DATE Time of this logging.
VARCHAR2(64) The name of the parent environment for the parent process instance indicated by
PARENTPROCID.
VARCHAR2(64) The name of the engine containing the parent process instance indicated by
PARENTPROCID.
Appendix B Engine Database Schema 353
Database Schema Reference
Table B-35 WFHProcessStateLog
Name Index Null?
ID
Type
NUMBER(38)
STATE NUMBER(38)
LOGTIME DATE
Description
Unique identifier for the process instance in this engine.
New state of the process instance:
405 – WFProcess.PREPARE_CREATE
410 – WFProcess.CREATED
420 – WFProcess.ACTIVE
430 – WFProcess.COMPLETED
435 – WFProcess.PREPARE_ABORT
440 – WFProcess.ABORTED
Time of this logging.
Table B-36 WFHRegistrationLog
Name Index Null?
APPLICATIONID
COMPATIBILITYLEVEL
PROJECTNAME
REGISTRATIONNAME
TYPE
OBSOLETE
Type Description
VARCHAR2(32) Name of the installed application for this iIS plan.
NUMBER(38) Compatibility level of the installed library of this iIS plan.
VARCHAR2(67) Name of the generated TOOL project of the compiled iIS plan.
VARCHAR2(64) Name of the source iIS plan from which the iIS component is derived.
NUMBER(38) Type of iIS plan:
NUMBER(38)
151-Process Definition
152-Validation
153-Assignment Rule
154-User Profile
Internal use only.
354 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
Table B-36 WFHRegistrationLog (Continued)
Name Index Null?
Type
STATE NUMBER(38)
LOGTIME DATE
Description
Effect of this registration action:
1 – Registered
-1 – Unregistered
Time of this logging.
Table B-37 WFHSessionLog
Name Index Null?
ID
SESSNAME
USERNAME
PROFILENAME
STATE
LOGTIME
Type
NUMBER(38)
Description
Unique identifier for the client session.
VARCHAR2(64) The session name (not logged on session termination).
VARCHAR2(64) The user name for the session user (not logged on session termination).
VARCHAR2(64) The profile name of the user on the session.
NUMBER(38) Logged new state for the session:
210 – WFSession.ACTIVE
DATE
220 – WFSession.SUSPENDED
230 – WFSession.TERMINATED
Time of this logging.
Table B-38 WFHTimerLog
Name Index Null?
ID
PROCESSID
TIMERNAME
LOGTIME
Type Description
NUMBER(38)
NUMBER(38)
Unique identifier for the timer instance within this engine.
Unique identifier for the process instance in which this timer instance occurs.
VARCHAR2(64) Name of the timer in the process definition.
DATE Time of this logging.
Appendix B Engine Database Schema 355
Database Schema Reference
Table B-39 WFHTimerStateLog
Name Index Null?
ID
PROCESSID
STATE
RELATIVETIME
CURRELATIVETIME
TIMETOALARM
LOGTIME
Type Description
NUMBER(38)
NUMBER(38)
NUMBER(38)
Unique identifier for the timer instance within this engine.
Unique identifier for the process instance in which this timer instance occurs.
New state of the timer:
810 – WFTimer.CREATED
820 – WFTimer.OFF
830 – WFTimer.ON
840 – WFTimer.EXPIRED
850 – WFTimer.DELETED
VARCHAR2(32) For an elapsed timer, the defined duration of time set for the timer, expressed in character form.
For a deadline timer, the defined expiration time set for the timer, expressed in character form.
VARCHAR2(32) For a paused elapsed timer, the duration remaining should the timer be turned on again without reset, expressed in character form.
For a paused deadline timer, the
“remembered” expiration time should the timer be turned on again without reset, expressed in character form.
DATE
DATE
For a running timer, the time when it is/was to expire.
Time of this logging.
356 iPlanet Integration Server • Process System Guide • August 2001
Database Schema Reference
State Values
Many of the history log tables listed in this section have a field that represents the state of a given engine object: process instance, activity, session, and timer. The following table shows the values corresponding to the various states of these objects:
Object
Process Instance
Activity
Timer
Session
State
PREPARE_CREATE
CREATED
ACTIVE
COMPLETED
PREPARE_ABORT
ABORTED
PENDING
READY
PREPARE_ACTIVE
ACTIVE
PREPARE_COMPLETE
COMPLETED
PREPARE_ABORT
ABORTED
DELETED
CREATED
OFF
ON
EXPIRED
DELETED
ACTIVE
SUSPENDED
TERMINATED
30
35
40
45
440
10
20
25
Value
405
410
420
430
435
830
840
850
210
50
60
810
820
220
230
Appendix B Engine Database Schema 357
Database Schema Reference
358 iPlanet Integration Server • Process System Guide • August 2001
Index
A
AbortActivity command, Conductor Script
AbortAllProcesses command, Conductor Script
ABORTED activity state
,
,
process instance state
,
,
aborting activities
process instances
AbortProcess command, Conductor Script
ACTIVE activity state
,
,
process instance state
,
session state
activities about
creation
methods, execution of
state transitions
status, checking
termination
activity execution automatic activities
offered activities
queued activities
subprocess activities
activity queues reprioritizing
status, checking
activity states
ABORTED
ACTIVE
changing
COMPLETED
,
,
DELETED
PENDING
process execution and
READY
,
transitions
,
activity types
alarms about
list and descriptions
monitoring
viewing
Alarms window
aliases about
registration
subprocess activity and
unregistration
Assignment Rule dictionary, registration
audit trace
automatic activities described
execution of
auto-reconnect mechanism, sessions
359
Section B
B backup engine unit defined
partitioning guidelines
BOTH governor state
BroadcastMessage command, Conductor Script
C cconsole command
central server node definition
installation
ChannelDisconnect alarm
client application development node
client applications
command summary
Conductor Script
iIS Console
CommitTransaction command, Conductor
Script
CompleteActivity command, Conductor Script
COMPLETED activity state
,
,
process instance state
,
,
component mode Conductor Script commands
Conductor Script about
command summary
component mode commands
engine management commands
engine status, showing
environment mode commands
iIS distributions
process execution management commands
starting
Conductor Script command
AbortActivity
AbortAllProcesses
AbortProcess
BroadcastMessage
CommitTransaction
360 iPlanet Integration Server • Process System Guide • August 2001
CompleteActivity
ConsultActivity
CreateActivity
CreateFilter
DelegateActivity
DeleteFilter
FindDBService
FindEngine
FindGovernor
FindNode
FindParentEngine
FindPrimary
FindUnit
FlushLog
IIOPServer
ListActivities
ListActivityQueues
ListConductorDistributions
ListEngines
ListFilters
ListProcesses
ListRegistrations
ListSessions
ListTimers
ListTransactions
MakeConductorDistribution
ModLogFlags
ReadyActivity
RegisterAlias
RegisterAssignmentRules
RegisterProcessDefinition
RegisterUserProfile
RegisterValidation
RemoveReadLock
RemoveWriteLock
Rollback Transaction
RollbackActivity
SendMessage
SetAttributeValue
SetPassword
SetPrimary
SetQueuedActivityPriority
SetState
SetTimer
SetTimerDeadline
SetTimerElapsed
ShowActivity
Conductor Script command (continued)
ShowActivityQueue
ShowConfiguration
ShowEngine
ShowLogFlags
ShowProcess
ShowSession
ShowStatus
ShowTimer
Shutdown
StartActivity
StartDBService
StartEngine
StartGovernor
StartTimer
StartUnit
StopTimer
SuspendAllSessions
SuspendSession
TerminateAllSessions
TerminateSession
Uninstall
UnRegisterAlias
UnRegisterAssignmentRules
UnRegisterProcessDefinition
UnRegisterUserProfile
WaitForStartup
configuration file, engine
ConsultActivity command, Conductor Script
CreateActivity command, Conductor Script
CREATED states
,
CreateFilter command, Conductor Script
current state tables engine database
schema
D data file, dump/restore facility
database
Dump/Restore facilities
engine
Section D enterprise
organization
database service configuring
,
defined
monitoring
partitioning guidelines
startup
database service state
DatabaseDisconnect alarm
DelegateActivity command, Conductor Script
DELETED states
DeleteFilter command, Conductor Script
development client node, installation
development engines
development repository
disconnect parameters, sessions
distributions iIS
making with Conductor Script
DrDump command, Conductor Script
DrRestore command, Conductor Script
Dump/Restore facilities
E
E1 governor state
E2 governor state
EMBRYONIC engine unit state
engine access, restricting
described
development engines
failover
functions
management tasks
management tools
monitoring with Conductor Script
monitoring with iIS Console
performance
performance tuning
process execution and
production engines
Index 361
Section E engine (continued) reconfiguration
recovery
,
registration manager
relation to iIS process management system
relocating
shutting down
shutting down components
starting with Conductor Script
starting with iIS Console
startup, monitoring
states, changing with Conductor Script
states, changing with iIS Console
status, showing
engine component backup engine unit
compiled vs. interpreted
database service
engine database
engine unit
governor
icons, state indicators
monitoring with Conductor Script
monitoring with iIS Console
partitioning
partners
shutting down
engine component log file
engine configuration about
component memory settings
configuration file
deleting
duplicating
failover
failover and load balancing
minimal, no failover
multiple
properties
,
recover cursor size
engine database
See also current state tables; history log tables;
registration log tables configuration file
configuration properties
,
controlling growth
defined
Dump/Restore facilities
failure
logging settings
,
managing
recovery options
relation to iIS process management system
schema
engine database tables about
list, alphabetical
list, category
registration table entries
registration tables
Engine Event Filter window
engine instrumentation performance chart
ShowStatus command
engine management, Conductor Script commands
engine partitioning
engine server node defined
installation
engine state changing
monitoring
engine unit configuring
defined
failover
failure
monitoring
startup
state, changing
states
EngineUnitForceStandby alarm
EngineUnitOnline alarm
EngineUnitShutdown alarm
environment mode, Conductor Script commands
362 iPlanet Integration Server • Process System Guide • August 2001
Section F exception alarm
exceptions, logged
execution options
Exit command, iIS Console
EXPIRED timer state
H history log schema, graphical representation
history log tables database schema
graphical representation
F failover, engine unit
failure engine
,
engine database
network connection
filtering engine events
iIS Console lists
FindDBService command, Conductor Script
FindEngine command, Conductor Script
FindGovernor command, Conductor Script
FindNode command, Conductor Script
FindParentEngine command, Conductor Script
FindPlan command, Conductor Script
FindPrimary command, Conductor Script
FindUnit command, Conductor Script
first activity, description
FlushLog command, Conductor Script
G
GenerateDistribution command, Conductor
Script
governor configuring
defined
monitoring
partitioning guidelines
startup
states
GovernorDisconnect alarm
I
IDLE governor state
IIOPServer command, Conductor Script
iIS Console command summary
engine list
exiting
list views
lists, filtering
lists, sorting
main window
menu bar
online help
overview
password protection
popup menu
starting
window refresh behavior
iIS distributions, registration
iIS process engine, See engine
iIS process management system
about
components
configuration
installation program
multiple engines
resource considerations
setup preparation
setup procedure
system software
uninstalling
implicit unregistration
Index 363
Section L installation central server
development client node
engine server node
runtime client node
instrument data, logged
L last activity, description
library distribution and registration
ListActivities command, Conductor Script
ListActivityQueues command, Conductor Script
ListConductorDistributions command, Conductor
Script
ListEngines command, Conductor Script
,
ListFilters command, Conductor Script
ListPlans command, Conductor Script
ListProcesses command, Conductor Script
ListRegistrations command, Conductor Script
ListSessions command, Conductor Script
ListTimers command, Conductor Script
ListTransactions command, Conductor Script
load balancing
log file about
engine component
registration
logging settings, engine database
message filters iIS
specifying
messages broadcasting
sending to sessions
ModLogFlags command, Conductor Script
monitoring engine startup
engine state
process execution
,
sessions
two-phase commit operations
N network failure
O
OFF timer state
,
offered activities described
execution of
ON timer state
ONLINE engine unit state
online help iIS Console
M
Maximum number of processes option
Maximum number of sessions option
memory options, engine component
memory requirements
Memory-resident process limit
P partitioning engine components
partner
password
Conductor Script
iIS Console
PDF files, viewing and searching
PENDING activity state
,
,
364 iPlanet Integration Server • Process System Guide • August 2001
Section Q performance chart
performance indicators
performance, engine
,
ping interval, session
PREPARE state (two-phase commit)
primary engine unit, partitioning guidelines
process attributes locks, removing
value, changing
value/lock state, checking
process client applications, See client applications
process creation
process definition, registration
process development node
process development workshops
process execution about
activity creation
activity execution
activity termination
analysis
bottlenecks, checking
configuration options
historical data
managing
monitoring
monitoring and management tasks
objects in engine, diagram
process creation
process termination
recovering state
recovery levels
reports
tuning
process history
process instance states
ABORTED
ACTIVE
COMPLETED
,
,
CREATED
process instances aborting
execution options
stalled
status, checking
swapping
process, analysis of
ProcessAbort alarm
production engines
production loads and memory
properties database configuration
engine configuration
performance chart
Q queued activities described
execution of
Quit command, iIS Console
R
READY activity state
,
,
ReadyActivity command, Conductor Script
reconfiguring engine
engine database logging
reconnect parameters, sessions
recover cursor size, process instances
recovery engine
engine database options
levels
state information
refresh behavior
Index 365
Section S
RegisterAlias command, Conductor Script
RegisterAssignmentRules command, Conductor
Script
registering
Conductor distributions
engine with alarm service
RegisterProcessDefinition command, Conductor
Script
RegisterUserProfile command, Conductor Script
RegisterValidation command, Conductor Script
registration about
aliases
,
assignment rule dictionary
engine registration manager
entities registered
iIS distributions
implicit unregistration
library distributions, and
order
performing
process definition
steps
unregistration
viewing
registration log tables about
entries, engine database
list, alphabetical
list, category
RemoveReadLock command, Conductor Script
RemoveWriteLock command, Conductor Script
reports, generating
repository central
management tools
setting up
repository server node
repository server, managing
requested message output, logged
restoring
engine database tables
session connections
RollbackActivity command, Conductor Script
RollbackTransaction command, Conductor
Script
runtime client node defined
installation
S
scripts comments in
running using the cscript -i flag
SendMessage command, Conductor Script
session states
ACTIVE
SUSPENDED
,
,
TERMINATED
sessions about
auto-reconnect
disconnect parameters
disruptions
management
messages, broadcasting to
messages, sending to
monitoring
reconnect parameters
setting maximum number
suspending
,
terminating
SetAttributeValue command, Conductor Script
SetPassword command, Conductor Script
SetPrimary command, Conductor Script
SetQueuedActivityPriority, Conductor Script
SetState command, Conductor Script
,
SetTimer command, Conductor Script
SetTimerDeadline command, Conductor Script
SetTimerElapsed command, Conductor Script
ShowActivity command, Conductor Script
ShowActivityQueue command, Conductor
Script
ShowConfiguration command, Conductor
Script
366 iPlanet Integration Server • Process System Guide • August 2001
Section T
ShowEngine command, Conductor Script
ShowLogFlags command, Conductor Script
ShowProcess command, Conductor Script
ShowSession command, Conductor Script
ShowStatus command, Conductor Script
ShowTimer command, Conductor Script
shutdown
Shutdown command, Conductor Script
,
sorting lists, iIS Console
stall, process instance
STANDBY engine unit state
StartActivity command, Conductor Script
StartDBService command, Conductor Script
StartEngine command, Conductor Script
StartGovernor command, Conductor Script
StartTimer command, Conductor Script
StartUnit command, Conductor Script
startup phases, primary engine unit
StartupFailure alarm
state database service
engine unit
process state values
process state, recovering
recovering process execution state
state transitions, activities
StopTimer command, Conductor Script
subprocess activities aliases and
described
execution of
SuspendAllSessions command, Conductor
Script
SUSPENDED session state
suspending sessions
SuspendSession command, Conductor Script
swap-out interval
synchronizing transactions
system design
system libraries
system maintenance engine, relocating
iIS system, uninstalling
nodes, adding
private repository, creating
repository server
system management node
T
TerminateAllSessions command, Conductor
Script
TERMINATED session state
,
TerminateSession command, Conductor Script
terminating process instances
sessions
timers expiration time, changing
state, changing
states
,
status, checking
Trace window about
client messages, writing to
message filters, setting
using
transactions, See two-phase commit
troubleshooting engine event messages, displaying
engine problems
tuning process execution
two-phase commit about
managing transactions
monitoring transactions
PREPARE state
Index 367
Section U
U
UDS runtime environment
Uninstall command, Conductor Script
uninstalling iIS
UnRegisterAlias command, Conductor Script
UnRegisterAssignmentRules command, Conductor
Script
UnRegisterProcessDefinition command, Conductor
Script
UnRegisterUserProfile command, Conductor
Script
unregistration about
aliases
Conductor distributions
iIS distributions
implicit
upgrading
Conductor system software
monolithic
rolling
user profile registration
UserAccess alarm
using list views, iIS Console
V validation, registration
W
WaitForStartup command, Conductor Script
WFEnvAgent, registration service
368 iPlanet Integration Server • Process System Guide • August 2001
advertisement
Key Features
- Process management and execution
- Integration of applications and systems
- Failover and load balancing
- Monitoring and troubleshooting
- Registration of processes
- Session management
- Two-phase commit transaction support
- Database management and recovery
- Script utility for system management
- Centralized development and deployment
