Process System Guide iPlanet™ Integration Server Version 3.
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.
Contents List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 List of Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Name Change . . . . . . . . . . . . . . . . . . .
iIS Process Management Tasks (continued) Managing iIS Process Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iIS Process Management Tools . . .
The iIS Console Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Main Viewing Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mouse Popup Menu . . . . . . . . . . . . . . . . . . . . . .
Reconfiguring an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Reconfigure an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Dynamically Modify Database Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Tune Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6 Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Engine Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disrupted Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Monitoring and Managing Two-Phase Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Managing Two-Phase Commit Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 8 Chapter 7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing iIS Process Engines with Conductor Script (continued) Monitoring Engines and Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Individual Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing Engine States . . . . . . . . . . . . . . . . . . .
Conductor Script Commands (continued) CreateFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conductor Script Commands (continued) RemoveWriteLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RollbackActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RollbackTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SendMessage . . . . . . . .
Appendix B Engine Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Tables by Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alphabetical Listing of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Schema Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures Figure 1-1 An iIS Process Management System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Figure 1-2 Minimal Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Figure 1-3 Engine Configuration with Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Figure 1-4 Engine Configuration with Both Failover and Load Balancing . . . . . . . . . . .
iPlanet Integration Server • Process System Guide • August 2001
List of Procedures To copy the documentation to a client or server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 To view and search the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Before you invoke the setccomp script, you must do the following . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 To set up an iIS process system . . . . . . . . . . . . . . . . . . . . . . . . . . .
To use the Dump/Restore application to restore database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 To transfer iIS library distributions to a production environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 To register one or more distributions using the iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 To unregister a process definition, assignment rule dictionary, or user profile . . . . . . . . . . . . . . . . .
To view all engine events for an existing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 To view all engine events for the next process instance of a specific process definition . . . . . . . . . . 220 To specify a custom filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 To view performance indicators for an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
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.
Text Conventions Chapter Description Chapter 8, “Using the Conductor Script Utility” Explains how to perform iIS system management tasks using Conductor Script commands. Appendix A, “Conductor Script Commands” Provides a command reference for Conductor Script, a command line tool for process system management. Appendix B, “Engine Database Schema” Provides a reference for the iIS process engine database schema.
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.
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.
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 the following location: Process development examples are installed at FORTE_ROOT/install/examples/conductr The PDF file, c_examp.pdf, describes how to install and run the examples in this directory.
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.
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+] To return to the iisdoc.pdf file, click the Homepage bookmark at the top of the bookmarks list. 6. 26 To revisit the query results, click the Results button at the bottom of the iisdoc.
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? 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.
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.
What Is an iIS Process Engine? An iIS Process Management System Figure 1-1 Process Develpment Workshops Central Development Repository Registration System Management Tools Process Engines Organization Database Engine Database Client Applications TOOL C++ CORBA/IIOP ActiveX JAVA 30 iPlanet Integration Server • Process System Guide • August 2001 Application Services Engine Enterprise Database Databases
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.
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 Figure 1-5 on page 37).
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).
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.
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.
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.
iIS Process Management Tasks Figure 1-5 Engine Manager Objects Engine Unit Engine Object Session Manager Registration Manager Process Manager Timer Manager Access Manager History 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 d
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.
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.
iIS Process Management Tools Managing process execution involves monitoring the activity of the engine and making administrative adjustments when necessary.
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 Chapter 8, “Using the Conductor Script Utility.
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.
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.
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 Components of an iIS Process System Figure 2-1 Process Develpment Workshops Central Development Repository Registration System Management Tools iIS Process Engines Organization Database Primary Engine Unit Client Applications Database Database Service Database Service Service Governor Engine Database TOOL Backup C++ CORBA/IIOP ActiveX JAVA Application Services Engine Enterprise Database Databases The components of an iIS process system, shown in Figure 2-1, are
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.
iIS Process System Software Table 2-1 Process System Software Modules (Continued) Software Module Category Description WFLibrary Process development A library distribution that supports the process development workshops. Needed in iIS process development repository and on process development nodes. Process development A library distribution that provides repository schema definitions used to create code in the process development workshops.
iIS Process System Software Table 2-1 Process System Software Modules (Continued) Software Module Category Description WFClientAPI C++ client application development 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. Java/IIOP client application development A server application (CORBA interface service) required to execute process client application code written in JAVA/IIOP.
iIS Process System Software Table 2-1 Process System Software Modules (Continued) Software Module Category Description WFEnvDefinition System A library distribution that provides underlying system management support for accessing iIS process engines and performing registration of process definitions. Needed on all nodes. System An application that supports generation and deployment of library distributions for registration of process definitions, assignment rule dictionaries, and user profiles.
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 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.
iIS Process System Software Figure 2-2 iIS Process System Configuration Central Server Process Development Environment Manager Process Development Workshops Repository Server Client Application Development Repository Service Client API Central Development Repository Engine Server System Management Tools Engine Database Conductor Console Engine Components Runtime Applications Application Servers Enterprise Database Application Services You do not have to decide at iIS installation time exac
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.
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.
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 “IIOPServer” on page 287).
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 FORTE_ROOT directory Prepares node as the central distribution node for all distributions.
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: 58 Operation Software Module FORTE_ROOT directory Transfers iIS repository files to node. WFSeed.btx WFSeed.btd install/resposcpy Installs engine components. WFEngineUnit WFGovernor WFDatabaseSvc userapp Installs process development libraries.
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 FORTE_ROOT directory Transfers iIS repository files to node. WFSeed.btx WFSeed.
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 Software Module FORTE_ROOT directory Installs iIS TOOL client libraries. WFClientLibrary WFProcMgrLibrary WFAdminLibrary userapp Installs iIS C++ client development DLL. WFClientAPI userapp Installs iIS process management client applications.
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 Chapter 4, “Managing Engines”), there are relatively few maintenance tasks that you need to perform. Most maintenance concerns the databases in the system.
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.
Maintaining an iIS Process System 3. 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. 4. 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.
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.
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.
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.
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. Enter a valid password if one is requested (see “Setting Password Protection for iIS Console” on page 71). ➤ 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.
The iIS Console Main Window The following table describes the command line flags for the cconsole command. Flag Description -fl log_flags /LOGGER=log_flags 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.
The iIS Console Main Window Figure 3-1 iIS Console Main Window Menu bar Active environment Engines 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 Engine is configured but has not been started. Transition Engine is in the process of starting up or shutting down. Online Engine has fully started and is online.
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.
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.
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.
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. Enter a new time interval in milliseconds. A time interval of zero turns off automatic refresh. 3. Click OK. ➤ To force an immediate refresh 1. Choose View > Refresh Now.
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.
Using iIS Console Windows Object State/Status Value Activity READY Activity ACTIVE Activity COMPLETED Activity ABORTED Timer ON Timer 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. 76 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. 2.
Using iIS Console Windows 4. If you select a text field, you can also specify that case-sensitivity apply to the displayed text by checking Case Sensitive Text Comparison. 5. 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.
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 78 Command Description See… Alarms… Lets you view all alarms received from the selected engine. page 208 Registrations… Provides submenus for registering (and unregistering) process definitions, assignment rules, user validations, and user profiles with one or more engines.
iIS Console Main Window Command Summary View Menu Command Description See… Refresh Now Forces an immediate refresh of the engine list in the main viewing panel. page 72 Set Refresh Interval… Opens a Refresh Interval window where you can set the time interval between automatic refreshes of the window display. page 72 Window List… Displays a list of open windows from which you can select a window to bring to the foreground.
iIS Console Main Window Command Summary Command Description See… Trace… Opens an engine trace window in which you display messages, of the type you specify, generated by the various engine components. page 212 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. page 217 Status… Opens an engine status window in which you can view the status of the selected engine or any of its components.
iIS Console Main Window Command Summary Command Description See… Activities Resident… 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.
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.
Production Engines Versus Development Engines Production Engine Development Engine State information is needed for recovery: current state logging to the engine database is always turned on. State information does not need to be stored in the engine database: current state logging can be turned off. Backup engine unit and governor is needed for failover. Failover is not critical: a minimal engine configuration is adequate.
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.
Configuring an Engine Figure 4-1 Engine Configuration with both Failover and Load Balancing Client Applications iIS Process Engine Governor Primary Engine Unit Backup Engine Unit Router Database Database Services Database Services Services Engine Database During installation, you decided which nodes in your iPlanet UDS environment (engine servers) would have engine components installed on them.
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.
Configuring an Engine Figure 4-2 Typical Engine Partitioning Scheme Clients Server 1 Governor Priority=9 Database Service Server 2 Primary Engine Unit Router Server 3 Backup Engine Unit Priority=8 Database Service Server 4 Engine Database Database Services Priority=10 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.
Configuring an Engine Engine name environment. An alpha-numeric name used to identify the engine in a given Environment An alpha-numeric name that specifies the iPlanet UDS environment in which the engine resides. Database Configuration Properties database.
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 Description environment Name of the iPlanet UDS environment in which engine resides. engine_name Name of the iIS engine. A sample configuration file is reproduced below: FILE_VERSION = 2.
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 Description FILE_VERSION string Internal use. Do not modify. GOVERNOR string Specifies the node on which governor component runs. UNITS string 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).
Configuring an Engine Table 4-1 Process Engine Configuration Properties (Continued) Property Type of value Description GOVERNOR_MEMORY_FLAG string Specifies memory options. Uses the same syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,…. DBSERVICE_MEMORY_FLAG string Specifies memory options. Uses the same syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,…. UNIT_MEMORY_FLAG string Specifies memory options.
Configuring an Engine Table 4-1 Process Engine Configuration Properties (Continued) Property Type of value Description MONITOR_DISPLAY_LIMIT 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.
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 Description environment Name of the iPlanet UDS environment in which engine resides. engine_name Name of the iIS engine. The database schema file uses XML to define SQL statements for the schema.
Configuring an Engine The following example shows how to modify the create index statement for the WFHActivity table to include a table space qualifier.
Configuring an Engine ➤ To configure a new engine 1. Choose Engine > New. The Configure New Engine window displays: 2. 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. 3.
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. 5. Property Description Process attribute segment size Specifies segment size for storing text-based process attributes. Default value is 255 bytes.
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”).
Configuring an Engine 7. Select the Components tab. The Component Partitioning dialog is displayed. 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.
Configuring an Engine 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.
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.
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.
Configuring an Engine The process execution options are the following: Process Execution Option Description Maximum number of sessions The maximum number of concurrent sessions supported by the engine. Attempts to open additional sessions will raise an exception. The default value is 300. Maximum number of processes The maximum number of concurrent process instance executions supported by the engine. Attempts to instantiate additional process instances will raise an exception.
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.
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.
Starting an Engine The governor has four internal states, depending on its connections with the engine units: Governor state Description IDLE Not connected to any engine units E1 Connected only to the first engine unit to start up (EngineUnit1) BOTH Connected to both engine units E2 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
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.
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).
Starting an Engine Startup Phase Description Phase # INFORM_PARTNER Communicates to partner that state has changed to online. 64 STARTUP_COMPLETE Completion of startup operations. Engine unit now online. 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.
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 110 1. Select an engine in the iIS Console main window. 2. Choose Engine > Start.
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 Description warm 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.
Starting an Engine 4. Disable the engine components you do not want to start. By default, all components specified in your configuration file are enabled. 5. 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.
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).
Reconfiguring an Engine 2. Choose Engine > Reconfigure. The Reconfigure Engine window displays: 3. Select the appropriate tab to modify the property or properties you want to change. 4. When you have finished reconfiguring your engine, click Save. The modified information is written to the engine configuration file. 5. 114 Restart your engine for reconfiguration changes to take effect.
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. Enable (or disable) the database tables to enable (or disable) logging. 4.
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.
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.
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.
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.
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.
Monitoring and Changing Engine States Property Description peak allocated memory 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 Description governor state the status of the governor’s connections with engine units (IDLE, E1, BOTH, E2) as described in “Governor” on page 105 start time the time at which the governor partition
Monitoring and Changing Engine States Property Description allocated memory the amount of active memory currently allocated to objects created by the engine unit partition peak allocated memory 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 comp
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.
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 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.
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.
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.
Managing an Engine Database 2. Configure a data file in which to dump the data. a. Click the Configure Files tab. b. 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. 128 c. In the Data file name field, enter the name of the data file. d. Click the Set Configuration button.
Managing an Engine Database 3. Specify the engine database from which to dump the data. a. Click the Configure Database tab. b. 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. c. Click the Open Connection button. The status bar at the bottom of the window displays a “Database Connected” message.
Managing an Engine Database 4. Dump the data. a. Click the Dump Tables tab. b. Select the category of tables you want to dump. By default, all categories are selected. Disable any category you do not want to dump. c. Click the Dump Tables button. d. 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.
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 Description -e engine_name The name of the iIS engine in the current environment. This flag is required. -d directory_name The directory in which to place the data files. The default value is the root directory.
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.
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. Follow the instructions under “Dumping Database Tables” on page 126. 2. 3. Configure a data file from which to retrieve the data. a. Click on the Configure Files tab. b.
Managing an Engine Database 4. Restore the data. a. Click the Restore Tables tab. b. Select the categories of tables you want to restore. By default, all categories are selected. Disable any category you do not want to restore. c. Click the Restore Tables button. d. Click OK in the Information dialog that is displayed. When tables have been successfully restored, the status bar displays the “Completed Restoring Tables” message.
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.
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. 136 Variable Description WFDR_ENGINE The name of the iIS engine. WFDR_DIRECTORY The directory in which to place the dump files. The default value is the directory in which the application resides.
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.
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 Registration Do?” below). 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.
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.
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 Primary Engine Unit 2 Place entry in registration table Engine Database Engine Server Backup Engine Unit • Installing library distribution files on the nodes hosting the target engine (more specifically, hosting the target engine units).
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.
About Registration 4. Follow the instructions for registering iIS distributions in “Registering iIS Distributions” on page 144. 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.
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.
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.
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.
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 146 2. To filter the list of distributions available for registration, select Process Definitions, Assignment Rule Dictionaries, User Profiles, or Validation from the Distributions drop list. 3.
Registering iIS Distributions Upgrading Registrations Sometimes you must register a new version (upgrade a registration) of one of these library distributions.
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. In the Distribution field, enter the name of the process definition, assignment rule dictionary, or user profile to unregister. 3. From the Type drop list, select the distribution type. 4.
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.
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 2. In the Alias name field, enter the name of the alias you want to unregister. 3.
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. Click a tab to view a particular type of registered distribution. 4. Check that the window’s refresh options are appropriately set.
Viewing Registrations for an Engine 3. 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. 4. Select the item to unregister and choose TabName > Unregister. NOTE You cannot unregister a validation.
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 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.
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.
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.
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.
Introduction Session state Description RECONNECTION_IN_PROGRESS 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.
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.
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.
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 “Activity Types” on page 165), as a general rule, the engine takes each activity through a succession of states shown in the following table and illustrated in Figure 6-1 on page 164.
Introduction Activity state Description ACTIVE 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.
Introduction Figure 6-1 Activity State Transitions—from Creation to Termination Activity State Process Execution Step Activity referenced by router of another activity Engine activates timer controls, if any. Engine executes Trigger method. PENDING If Trigger method returns TRUE, Engine executes Ready method, if any. Ready method finishes Engine activates timer controls, if any. READY Engine offers activity to sessions/queues (offered or queued activity).
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 Description First Specialized activity: the first activity in a process definition.
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
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.
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.
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.
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.
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.
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 d
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.
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.
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.
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.
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.
Monitoring and Managing Engine Sessions 178 2. Open the session of interest. 3. Click Send Message. The Send Message window displays: 4. Type the message in the Message field. 5. Select the urgency: Informational or Critical. 6. Click Send.
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. Type the message in the Message field. 4. Select the urgency: Informational or Critical. 5. Click Send.
Monitoring and Managing Process Execution Figure 6-2 Process Execution Objects: Properties and Relationships Session Activity Instance Activity list Session id Session name User Status Transaction id 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 iI
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.
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.
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.
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. See Step 1 through Step 5 under “Checking the Status of a Process Instance” on page 181. 2. Click the Abort Process button.
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.
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.
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.
Monitoring and Managing Process Execution 3. From the New state drop list, select the new state of the activity. 4. 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.
Monitoring and Managing Process Execution 3. Select a queue. 4. 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.
Monitoring and Managing Process Execution 3. Choose Activity > Set Priority. The Set Queued Activity Priority window displays: 4. In the New prioritizing value, change the value of the queue prioritizing process attribute. 5. 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.
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. For each timer, the list displays the timer name, timer state, and expiration time. 2. Select a timer.
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. See Step 1 through Step 3 under “Checking the Status of a Timer” on page 191. 2. 192 Click the Set State button.
Monitoring and Managing Process Execution 3. To change the state of the timer, click one of the radio buttons in the On/Off Control. 4. To change the expiration time, click one of the radio buttons in the Options box. ❍ ❍ 5. 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).
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.
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. Enter a new value. 4. Click the Set button.
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. The engine must be running. 2. Choose Monitor > Activities Resident.
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.
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.
Monitoring and Managing Two-Phase Commit Object State Value Activity PENDING 10 READY 20 PREPARE_ACTIVE 25 ACTIVE 30 PREPARE_COMPLETE 35 COMPLETED 40 PREPARE_ABORT 45 ABORTED 50 DELETED 60 CREATED 810 OFF 820 ON 830 EXPIRED 840 DELETED 850 ACTIVE 210 SUSPENDED 220 TERMINATED 230 Timer Session 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 ap
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 Transactions Application Services 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.
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.
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.
Chapter 7 Troubleshooting This chapter discusses a number of topics and approaches related to diagnosing problems in your iIS process management system.
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.
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 Description ChannelDisconnect A communication channel to the engine unit has been disconnected due to the failure of a component or an interruption of the network.
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.
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.
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 “Filtering iIS Console Lists” on page 73. ➤ To search for an alarm in the Process Engine Alarms window 1. Choose Alarms > Find. The Filter Expression window opens. 2.
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.
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 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.
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.
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 Figure 7-1. Generally you 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.
iIS Console Trace Window iIS Message Filters iIS message filters follow the general guidelines above and have the following particularities: trc (debug) Message type cr (iIS runtime) Service type Group number Group Description 1 Engine 2 Session 3 Process 4 Activity 5 Timer 6 currently not used 7 History 8 Access checking 9 Recovery 10 Registration 13 Client application messages Level number 214 iIS uses the following group designations: iIS uses the following level designati
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).
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.
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.
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 speci
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.
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.
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.
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.
Performance Charts ➤ To view performance indicators for an engine 1. Select a running engine in the iIS Console main window. 2. Choose Monitor > Performance. 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. 3. You can change the interval between each update to the chart by changing the Update Every ___ seconds field.
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.
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. Define a name and location for the performance log data file. 3. Click OK. 4. Choose File > Start Logging to File. ➤ To stop logging performance information At the Performance Charts window, choose File > Stop Logging to File.
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.
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.
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.
Working with Conductor Script Flag Description -fm memory_options /MEMORY= memory_options 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. -i input_file /INPUT=input_file Specifies an input file.
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 Arguments Function AddAlias alias_name command_string Define an alias for a Conductor Script command and its arguments.
Working with Conductor Script Command Arguments Function UseLocal —— Set Conductor Script to recognize file names specified in local operating system format. UsePortable —— 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.
Working with Conductor Script The following table lists Conductor Script commands most often used for writing and executing scripts: Command Arguments Function CommentOff —— Stop writing script file commands and output to standard output. CommentOn —— Write script file commands and output to standard output. Delay milliseconds Delay execution of the next command for the specified number of milliseconds. Include filename Execute the commands in a specified script file.
Working with Conductor Script 234 Command Arguments Function CopyFile file1_name file2_name [r] Copy a specified file in the local file system. Cp file1_name file2_name [r] Copy a specified file in the local file system. Directory directory_name List the files in a directory. Duplicate file1_name file2_name [r] Copy a specified file in the local file system. ExecCmd opsys_cmd [bg_flag] [in_file] [out_file] [err_file] Execute the specified operating system command.
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.
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.
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 Arguments Function See… ListEngines —— Display a list of all running and configured iIS process engines in the environment. page 289 FindEngine engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
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.
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.
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 engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running. page 284 ListEngines —— Display a list of all running and configured iIS process engines in the environment.
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 See… FindEngine engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
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.
Managing Registrations with Conductor Script Command Arguments Function See… SetPrimary unit_name 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. page 301 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.
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. Use the ListPlans command to display iIS plans in the workspace. 4. Use the FindPlan command to make a particular plan current. 5. Use the CompilePlan command to create a TOOL project for the plan. 6. Use the MakeConductorDistribution command to generate an iIS library distribution.
Managing Registrations with Conductor Script Command Arguments Function AddSupplierPlan plan_name Include a plan as a supplier plan to the current plan. Commit —— Commit changes to current workspace. CompilePlan [force_flag] compile all out-of-date components in a plan. ExportPlan file_name [node | ids] Export all components of a plan to an export file. FindPlan plan_name Make the specified plan current. ImportPlan file_name Import a plan from the specified file.
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.
Managing Registrations with Conductor Script Command Arguments Function See… RegisterAlias alias_name process_name engine_name environment Register the alias—representing a specified process running on a specified engine in a specified environment—with the current engine. page 294 Register AssignmentRules [dictionary_name] Register all assignment rule dictionaries or the specified dictionary with the current engine.
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.
Managing Process Execution with Conductor Script Command Arguments Function See… UnRegister AssignmentRules dictionary_name [rule_name] Unregister all assignment rules (or just the specified assignment rule) in the specified assignment rule dictionary from the current engine. page 322 UnRegister ProcessDefinition process_name Unregister the specified process definition from the current engine.
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.
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 Arguments Function See… BroadcastMessage message_text priority Send a message with the specified priority to all sessions connected to the engine. The priority is a text string meaningful to the receiver. page 275 FindEngine engine_name Set specified engine as the “current” engine.
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.
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 Step 1 through Step 4 above. 2.
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. Use the CreateFilter command to filter the list of timers, if desired. 4. Use the ListTimers command to display a list of filtered timers. 5. Use the ShowTimer command to display information about a particular timer.
Managing Process Execution with Conductor Script ➤ To change the value of a process attribute 1. Display a list of attributes as described in Step 1 through Step 4 above. 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 Step 1 through Step 4 above. 2. Use the RemoveReadLock command to remove a read lock, or the RemoveWriteLock command to remove a write lock.
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 Arguments Function See… AbortActivity process_id activity_name Place the specified activity in the ABORTED state. page 273 AbortAllProcesses —— Abort all process instances in the current engine. page 274 AbortProcess process_id Abort the specified process instance.
Managing Process Execution with Conductor Script Command Arguments Function See… ListFilters —— List all existing event filters for the current engine. page 289 ListProcesses [short], [name process_name] 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. page 289 ListTimers —— List all timers in the current engine.
Managing Process Execution with Conductor Script Command Arguments Function See… ShowActivityQueue process_name, [queue_name] Display the contents of the specified queue (or all queues) for the specified process in the current engine. page 305 ShowProcess process_id Show details of specified process instance, including all activities and the values of all process attributes. page 307 ShowTimer process_id timer_name Show details of the specified timer.
Managing Process Execution with Conductor Script Command Arguments Function See… ShowProcess process_id Indicates any in-progress two-phase commit transactions in the process. page 307 ShowSession 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: page 308 Two phase commit mode is enabled. There is a client operation “CompleteActivity” in PREPARE phase.
Managing Process Execution with Conductor Script Command Argument ListTransactions RollbackTransaction session_ID transaction_ID Function See… Lists information for all in-progress iIS engine transactions (that is, those in a PREPARE phase) for all sessions in the current engine. page 291 Rolls back the in-progress iIS transaction for the specified session or transaction ID. page 298 ➤ To resolve transactions after a client or engine failure 1.
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.
Conductor Script Command Summary Figure A-1 Hierarchy of Conductor Script Levels Environment Mode Environment Engine Mode Engine 2 Component Mode Governor Engine 2 Engine 2 Backup Engine Unit Database Service 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.
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 Arguments Function See… FindEngine engine_name Set specified engine as the “current” engine. The engine (nor any of its components) does not have to be running.
Conductor Script Command Summary Command Arguments Function See… SetPassword [old_password] [new_password] 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. page 300 ShowEngine engine_name Display status of the specified engine.
Conductor Script Command Summary Command Arguments Function See… FindNode node_name Set the specified node as the “current” node. The node must exist in the environment. page 285 FindPrimary —— Set the primary engine unit for the current engine as the current component. The primary unit must be ONLINE. page 285 FindUnit unit_name Set the specified engine unit for the current engine as the current component. The engine unit must be running.
Conductor Script Command Summary Command Arguments Function See… StartEngine [newLog] [newState] [newRegistration] [cold] Start all components of the engine as specified in the engine configuration file. (Includes various start options that create new engine database tables.) page 315 StartGovernor —— Start the governor for the current engine on the current node. page 316 StartUnit unit_name [cold] Start the specified engine unit for the current engine on the current node.
Conductor Script Command Summary Command Arguments Function See… AbortActivity process_id, activity_name Place the specified activity in the ABORTED state. page 273 AbortAllProcesses —— Abort all process instances in the current engine. page 274 AbortProcess process_id Abort the specified process instance. page 274 BroadcastMessage message_text, priority Send a message with the specified priority to all sessions connected to the engine.
Conductor Script Command Summary Command Arguments Function See… DelegateActivity process_id, activity_id state delegation_rule [user_name] [other_info] 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. page 281 DeleteFilter filter_id Delete the specified filter.
Conductor Script Command Summary Command Arguments Function See… ReadyActivity process_id, activity_name Change the state of the specified activity from PENDING to READY. page 293 RegisterAlias alias_name, process_name, engine_name, environment Register the alias—representing a specified process running on a specified engine in a specified environment—with the current engine.
Conductor Script Command Summary Command Arguments Function See… SetQueuedActivity Priority process_id, activity_id prioritizing_value Reprioritize activities in an activity queue by setting the prioritizing process attribute for a specified activity to a specified value.
Conductor Script Command Summary Command Arguments Function See… SuspendAllSessions —— Suspend all active sessions in the current engine. page 319 SuspendSession session_id Suspend the specified active session. page 320 Terminate all sessions in the current engine. page 320 TerminateAllSessions TerminateSession session_id Terminate the specified session. page 321 UnRegisterAlias alias_name Unregister the specified alias from the current engine.
Conductor Script Command Summary Generic component A few commands work for any current component. Command Parameters Function See… ShowStatus [short] 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. page 309 ShowLogFlags —— Display the logger message filters (logger flags) set for the current component (partition logger settings).
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.
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.
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.
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.
Conductor Script Commands ConsultActivity process_id activity_id state consultation_rule return_rule [user_name1 [other_info1] [user_name2 [other_info2]]] Argument Description process_id The process instance in which the activity was created. activity_id The activity instance to be delegated. state 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.
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.
Conductor Script Commands CreateFilter The CreateFilter command creates a filter for events posted on the current engine object. CreateFilter time_interval filter_expression Argument Description time_interval The time during which the filter batches up events before reporting them, in milliseconds. filter_expression 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.
Conductor Script Commands Object Class Class Value Description Session 1 Events involving sessions Process instance 2 Events involving process instances Activity 3 Events involving activities Engine 4 Events involving engine objects Timer 5 Events involving timers Registration 6 Events involving registrations Object Instance This element specifies a particular instance identification, if desired—for example, a session name, activity name, or process ID.
Conductor Script Commands Operator Meaning > greater than <= less than or equal to >= greater than or equal to and logical and or logical or not logical not Examples Some example filter expressions follow: Filter Expression Meaning class = 1 and name = “Session1” Filter all events from the session whose name is “Session1”. type =1 and class = 2 Filter all process creations. type = 4 Filter all alarms. class = 3 and process_id = 45 Filter all events from the activities of process 45.
Conductor Script Commands Argument 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 (““). other_info Otherinfo string of the user name passed to the delegation_rule, if any.
Conductor Script Commands DeleteFilter The DeleteFilter command deletes the specified event filter in the current engine. DeleteFilter filter_id Argument Description filter_id 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.
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.
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).
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.
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.
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.
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.
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.
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.
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).
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.
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 “About Aliases” on page 143. 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.
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.
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.
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.
Conductor Script Commands RollbackActivity The RollbackActivity command changes the state of the specified activity from ACTIVE to READY. RollbackActivity 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 RollbackActivity command is available only when an engine is current, so you must first use the FindEngine Script command to set the current engine.
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.
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.
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.
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.
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.
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 The process instance of the specified timer. timer_name The name of the specified timer. state The specified new state: ON, OFF, or no change.
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
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.
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.
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 di
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.
Conductor Script Commands engine unit: (See also “primary engine unit:” on page 311.
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.
Conductor Script Commands Instrument Description ActiveActivities Number of current ACTIVE activities CurrentActivities Number of current activities = PendingActivities + ReadyActivities + ActiveActivities CompletedActivities Number of completed activities (terminated) since engine startup AbortedActivities Number of aborted activities (terminated) since engine startup TotalActivities Number of activities since engine startup = CurrentActivities + CompletedActivities + AbortedActivities 312 Ru
Conductor Script Commands Instrument Description LoginUserName The database user (login) name. LoggingState The database logging settings: the tables to which the engine is logging state and history information. TransactionCommitTime The average time it takes the engine to commit a change of state (complete a transaction involving the engine database). DatabaseType The database management system: ORACLE, SYBASE, etc.
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.
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.
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.
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 Step 10 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.
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.
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.
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.
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.
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 “About Aliases” on page 143.
Conductor Script Commands Argument Description rule_name 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.
Conductor Script Commands UnRegisterUserProfile The UnRegisterUserProfile command deletes the specified user profile from the current engine’s registration database. UnRegisterUserProfile user_profile_name Argument Description user_profile_name 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.
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.
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 “Alphabetical Listing of Tables” on page 329.
Database Tables by Category Current State Tables Registration Tables History Log Tables WFHProcParameters WFHTerminatedProcs WFHTermProcParas WFHActivity WFHActivityLog* WFHActStateLog* WFHQueuedActivity WFHRoleBasedAct WFHActivityTokens WFHActivityUsers WFHAssignment WFHSession WFHSessionLog* WFHSessionRole WFHSessAttributes WFHRetryInfo WFHTimer WFHTimerLog* WFHTimerStateLog* WFHActiveTimer WFHComplexRule WFHControl WFHRecoveryHelp WFHColdStart WFHColdStartLog WFHPerformanceLog WFHAlarmLog * c
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 WFHActiveTimer page 332 Active timers that are not in memory. WFHActivity page 332 Activity instances that are current in the engine. WFHActivityLog page 348 Log of activity instances (both current and past) in the system.
Alphabetical Listing of Tables Table B-1 330 Engine Database Tables (Continued) Database Table See… Description WFHControl page 337 System maintained table of sequence values for producing unique IDs for process, session, and timer instances. WFHLocks page 337 The type of access held on all instances of process attributes. WFHPerformanceLog page 351 Provides performance statistics for the engine. Average time measurements are expressed in milliseconds.
Database Schema Reference Table B-1 Engine Database Tables (Continued) Database Table See… Description WFHSessionRole page 344 Current client sessions and their roles. If a session has multiple roles, this table has a separate row for each role. WFHTerminatedProcs page 344 Internal use only. Managed by the engine to track aborted synchronous subprocesses. WFHTermProcParas page 345 Internal use only. Managed by the engine to track output parameters from aborted synchronous subprocesses.
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-1 on page 329.
Database Schema Reference Table B-3 WFHActivity (Continued) Name Index Null? TYPE Type Description NUMBER(38) 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.
Database Schema Reference Table B-3 WFHActivity (Continued) Name Index Null? Type Description ACTNAME VARCHAR2(64) The name of the activity in the process definition. ABORTRACTION NUMBER(38) Abort routing information. Internal use only. WUSER VARCHAR2(64) The “LinkedUser” information passed into this activity by its activity link. If there is no activity link, value is “” OTHERINFO VARCHAR2(64) The “OtherInfo” information passed into this activity by its activity link.
Database Schema Reference Table B-4 WFHActivityTokens Name Index Null? Type Description PROCESSID ✔ NOT NULL NUMBER(38) Unique identifier for the process instance in which this activity instance occurs. ACTIVITYID ✔ NOT NULL NUMBER(38) Unique identifier for a pending activity instance within the process instance in which it occurs. ACTIVITYNAME VARCHAR2(64) The name of an activity that is an immediate predecessor of the activity instance identified by the ACTIVITYID in this row.
Database Schema Reference Table B-6 WFHAssignment Name Index Null? Type Description PROCESSID ✔ NOT NULL NUMBER(38) Unique identifier for the process instance in which this activity instance occurs. ACTIVITYID ✔ NOT NULL NUMBER(38) Identifier for the activity instance in the process instance designated by PROCESSID. ID ✔ NUMBER(38) Identifier for the assignment rule. LINKEDUSER VARCHAR2(64) The “LinkedUser” information passed into this activity by its activity link.
Database Schema Reference Table B-8 WFHComplexRule Name Index PROCESSID ACTIVITYID Type Description ✔ NUMBER(38) Unique identifier for the process instance in which this activity instance occurs. ✔ NUMBER(38) Identifier for the activity instance in the process instance designated by PROCESSID. Type Description NEXTSESSIONID NUMBER(38) System maintained sequence for session ID values. NEXTPROCESSID NUMBER(38) System maintained sequence for process ID values.
Database Schema Reference Table B-10 WFHLocks (Continued) Name Index Null? LOCKTYPE Type Description NUMBER(38) Type of access to the process attribute: 1 – WFAttributeAccessor.READ 2 – WFAttributeAccessor.READQ 3 – WFAttributeAccessor.WRITE 4 – WFAttributeAccessor.WRITEQ 5 – WFAttributeAccessor.NO_LOCK ✔ NUMBER(38) Unique identifier for the attribute accessor instance within the process instance.
Database Schema Reference Table B-12 WFHProcess Name Index Null? Type Description ID ✔ NOT NULL NUMBER(38) Unique identifier for the process instance in this engine. NUMBER(38) Type of process (means of process creation): TYPE 1 – Process 2 – Subprocess STATE NUMBER(38) State of the process instance: 405 – WFProcess.PREPARE_CREATE 410 – WFProcess.CREATED 420 – WFProcess.ACTIVE 430 – WFProcess.COMPLETED 435 – WFProcess.PREPARE_ABORT 440 – WFProcess.
Database Schema Reference Table B-12 WFHProcess (Continued) Name Index Type Description NEXTACTIVITYID NUMBER(38) Sequence for the next activity instance within this process instance. INTERNALNAME VARCHAR2(138) Internal use only. PROCNAME VARCHAR2(64) The name of the process definition of which this running process is an instance. NUMBER(38) The recovery level designated for this process: RECOVERYLEVEL Null? NOT NULL 0 – WFProcess.RCVR_NORMAL 501 – WFProcess.RCVR_ONLY 502 – WFProcess.
Database Schema Reference Table B-13 WFHProcParameters Name Index Null? Type Description PROCESSID ✔ NOT NULL 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). Null? Type Description NOT NULL NUMBER(38) Identifier for the activity being queued.
Database Schema Reference Table B-16 WFHRetryInfo Name Index Null? Type Description GROUPID ✔ NOT NULL NUMBER(38) Identifier for the session between the engine and client. NOT NULL NUMBER(38) Identifier for the retry attempt. PROCESSID NUMBER(38) Unique identifier for a process instance in the engine. ACTIVITYID NUMBER(38) Identifier for an activity instance in the process instance designated by PROCESSID. REQSTATUS NUMBER(38) Internal use only.
Database Schema Reference Table B-18 WFHSessAttributes Name Index Null? Type Description SESSIONID ✔ NOT NULL NUMBER(38) Identifier for the session between the engine and client application. ATTNAME NOT NULL VARCHAR2(64) Name of a process attribute in the session. ATTTYPE NOT NULL NUMBER(38) The type of the process attribute. ATTSEGMENTID NOT NULL NUMBER(38) Internal use only. ATTSEGLENGTH NOT NULL NUMBER(38) Internal use only.
Database Schema Reference Table B-20 WFHSessionRole Name Index SESSIONID ROLENAME Null? Type Description NOT NULL 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? Type Description COMBINEDID ✔ NOT NULL VARCHAR2(158) Internal use only. PROCESSID NUMBER(38) Unique identifier for a process instance in the engine.
Database Schema Reference Table B-22 WFHTermProcParas Name Index Null? Type Description COMBINEDID ✔ NOT NULL VARCHAR2(158) Internal use only. ATTNAME VARCHAR2(64) The name of the attribute that must be returned to the calling process (an output parameter). ATTTYPE NUMBER(38) Attribute type. ATTSEGMENTID NUMBER(38) Internal use only. ATTSEGLENGTH NUMBER(38) Internal use only.
Database Schema Reference Table B-23 WFHTimer (Continued) Name Index Null? CURRELATIVETIME 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. For a paused deadline timer, the “remembered” expiration time should the timer be turned on again without reset, expressed in character form. TIMETOALARM DATE For a running timer, the time when it will expire.
Database Schema Reference Table B-25 WFHRegistration Name Index Null? Type Description APPLICATIONID ✔ NOT NULL VARCHAR2(32) Name of the installed application for this iIS plan. COMPATIBILITYLEVEL ✔ NOT NULL NUMBER(38) Compatibility level of the installed library of this iIS plan. LIBRARYNAME VARCHAR2(64) Name of the installed library for this iIS plan. LOADOPTIONS NUMBER(38) Internal use only. PROJECTNAME VARCHAR2(67) Name of the generated TOOL project of the compiled iIS plan.
Database Schema Reference Table B-26 WFHActivityLog Name Index Null? Type Description ID NUMBER(38) Unique identifier for this activity instance within the process instance in which it occurs. ACTNAME VARCHAR2(64) The name of the activity in the process definition. CREATETIME DATE Time that the activity instance was created. PROCESSID NUMBER(38) Unique identifier for the process instance in which this activity instance occurs. LOGTIME DATE Time of this logging.
Database Schema Reference Table B-27 WFHActStateLog (Continued) Name Index Null? Type Description SESSIONID NUMBER(38) ID of the session that owns this activity (if the activity is ACTIVE). LOGTIME DATE Time of this logging. Type Description ALARMTYPE VARCHAR2(64) The type of the alarm. DETAILS VARCHAR2(255) The text of the alarm. LOGTIME DATE Time of this logging. Type Description ALIAS VARCHAR2(64) Name of an alias registered (or now unregistered) on this engine.
Database Schema Reference Table B-30 WFHAttribLockLog Name Index Null? Type Description PROCESSID NUMBER(38) Unique identifier for the process instance in which this process attribute occurs. ACTIVITYID NUMBER(38) If the access to the process attribute is associated with an activity, the unique identifier for this activity instance. SESSIONID NUMBER(38) If the access to the process attribute is associated with a user session, the unique identifier for this session.
Database Schema Reference Table B-32 WFHPerformanceLog Name Index Null? Type Description SAMPLETIME NOT NULL DATE Date time stamp for the sample. RESPONSETIME NOT NULL NUMBER(38) Average engine response time to requests by a client application. SWAPINTIME NOT NULL NUMBER(38) Average process swap in time. SWAPOUTTIME NOT NULL NUMBER(38) Average process swap out time. TXCOMMITTIME NOT NULL NUMBER(38) Average engine transaction commit time.
Database Schema Reference Table B-32 WFHPerformanceLog (Continued) Name Index Null? Type Description ACTIVEPAGE NOT NULL NUMBER(38) The number of active memory pages for the engine. ALLOCATEPAGE NOT NULL NUMBER(38) The number of allocated memory pages for the engine. Null? Type Description PROCESSID NUMBER(38) Unique identifier for the process instance in which this process attribute occurs. ATTNAME VARCHAR2(64) Name of the process attribute.
Database Schema Reference Table B-34 WFHProcessLog Name Index Null? Type Description ID NUMBER(38) Unique identifier for the process instance in this engine. PROCNAME VARCHAR2(64) The name of the process definition of which this process is an instance. SUBMITTIME DATE Date and time the process instance was begun. PARENTACTIVITY NUMBER(38) For a subprocess, the activity ID of the subprocess activity instance in the parent process that invoked this process.
Database Schema Reference Table B-35 WFHProcessStateLog Name Index Null? Type Description ID NUMBER(38) Unique identifier for the process instance in this engine. STATE NUMBER(38) 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 LOGTIME DATE Time of this logging.
Database Schema Reference Table B-36 WFHRegistrationLog (Continued) Name Index Null? STATE Type Description NUMBER(38) Effect of this registration action: 1 – Registered -1 – Unregistered LOGTIME DATE Time of this logging. Type Description ID NUMBER(38) Unique identifier for the client session. SESSNAME VARCHAR2(64) The session name (not logged on session termination). USERNAME VARCHAR2(64) The user name for the session user (not logged on session termination).
Database Schema Reference Table B-39 WFHTimerStateLog Name Index Null? Type Description ID NUMBER(38) Unique identifier for the timer instance within this engine. PROCESSID NUMBER(38) Unique identifier for the process instance in which this timer instance occurs. STATE NUMBER(38) New state of the timer: 810 – WFTimer.CREATED 820 – WFTimer.OFF 830 – WFTimer.ON 840 – WFTimer.EXPIRED 850 – WFTimer.
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.
Database Schema Reference 358 iPlanet Integration Server • Process System Guide • August 2001
Index A AbortActivity command, Conductor Script 273 AbortAllProcesses command, Conductor Script 274 ABORTED activity state 163, 199, 357 process instance state 173, 198, 357 aborting activities 186 process instances 181 AbortProcess command, Conductor Script 274 ACTIVE activity state 163, 199, 357 process instance state 198, 357 session state 158, 199, 357 activities about 162 creation 167 methods, execution of 164 state transitions 168 status, checking 185 termination 171 activity execution automatic acti
Section B B backup engine unit defined 33 partitioning guidelines 86 BOTH governor state 106 BroadcastMessage command, Conductor Script 275 C cconsole command 67 central server node definition 51 installation 57 ChannelDisconnect alarm 205 client application development node 52 client applications 45 command summary Conductor Script 261 iIS Console 78 CommitTransaction command, Conductor Script 275 CompleteActivity command, Conductor Script 276 COMPLETED activity state 163, 199, 357 process instance state
Section D Conductor Script command (continued) ShowActivityQueue 305 ShowConfiguration 306 ShowEngine 306 ShowLogFlags 307 ShowProcess 307 ShowSession 308 ShowStatus 309 ShowTimer 313 Shutdown 314 StartActivity 314 StartDBService 315 StartEngine 315 StartGovernor 316 StartTimer 317 StartUnit 317 StopTimer 319 SuspendAllSessions 319 SuspendSession 320 TerminateAllSessions 320 TerminateSession 321 Uninstall 321 UnRegisterAlias 322 UnRegisterAssignmentRules 322 UnRegisterProcessDefinition 323 UnRegisterUserPr
Section E engine (continued) reconfiguration 113 recovery 34, 166 registration manager 142 relation to iIS process management system 45 relocating 62 shutting down 124 shutting down components 243 starting with Conductor Script 235 starting with iIS Console 110 startup, monitoring 112 states, changing with Conductor Script 242 states, changing with iIS Console 122 status, showing 309 engine component backup engine unit 33 compiled vs.
Section F exception alarm 205 exceptions, logged 210 execution options 103 Exit command, iIS Console 71 EXPIRED timer state 199, 357 H history log schema, graphical representation 198 history log tables database schema 347 engine database 124, 327 graphical representation 198 F failover, engine unit 33 failure engine 34, 159 engine database 125 network connection 159 filtering engine events 217 iIS Console lists 73 FindDBService command, Conductor Script 283 FindEngine command, Conductor Script 236, 239,
Section L installation central server 57 development client node 59 engine server node 58 runtime client node 60 instrument data, logged 211 L last activity, description 165 library distribution and registration 139 ListActivities command, Conductor Script 287 ListActivityQueues command, Conductor Script 287 ListConductorDistributions command, Conductor Script 288 ListEngines command, Conductor Script 239, 240, 289 ListFilters command, Conductor Script 289 ListPlans command, Conductor Script 244 ListProce
Section Q performance chart 221, 224 performance indicators 222 performance, engine 89, 116 ping interval, session 159 PREPARE state (two-phase commit) 201 primary engine unit, partitioning guidelines 86 process attributes locks, removing 194 value, changing 194 value/lock state, checking 189 process client applications, See client applications process creation 166 process definition, registration 145 process development node 52 process development workshops 45 process engine, See engine process execution
Section S RegisterAlias command, Conductor Script 294 RegisterAssignmentRules command, Conductor Script 294 registering Conductor distributions 145 engine with alarm service 206 RegisterProcessDefinition command, Conductor Script 295 RegisterUserProfile command, Conductor Script 295 RegisterValidation command, Conductor Script 296 registration about 137–142 aliases 144, 148 assignment rule dictionary 144 engine registration manager 142 entities registered 138 iIS distributions 144, 243 implicit unregistrat
Section T ShowEngine command, Conductor Script 306 ShowLogFlags command, Conductor Script 307 ShowProcess command, Conductor Script 307 ShowSession command, Conductor Script 308 ShowStatus command, Conductor Script 239, 240, 309 ShowTimer command, Conductor Script 313 shutdown 124, 243 Shutdown command, Conductor Script 243, 314 sorting lists, iIS Console 76 stall, process instance 173 STANDBY engine unit state 107 StartActivity command, Conductor Script 314 StartDBService command, Conductor Script 315 Sta
Section U U UDS runtime environment 44 Uninstall command, Conductor Script 321 uninstalling iIS 64 UnRegisterAlias command, Conductor Script 322 UnRegisterAssignmentRules command, Conductor Script 322 UnRegisterProcessDefinition command, Conductor Script 323 UnRegisterUserProfile command, Conductor Script 324 unregistration about 142 aliases 150 Conductor distributions 147 iIS distributions 142 implicit 142, 144 upgrading Conductor system software 63 monolithic 154 rolling 155 user profile registration 14
