Sun Microsystems iPlanet Integration Server 3.0 Process System Manual

Process System Guide

iPlanet™ Integration Server

Version 3.0

August 2001

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries.

This document and the product to which it pertains are distributed under licenses restricting their use, copying, distribution, and decompilation. No part of the product or of this document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.

Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.

Sun, Sun Microsystems, the Sun logo, Java, iPlanet and the iPlanet logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc.

UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.

Federal Acquisitions: Commercial Software – Government Users Subject to Standard License Terms and Conditions.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Sun Microsystems, Inc. a les droits de propriété intellectuels relatants à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et sans la limitation, ces droits de propriété intellectuels peuvent inclure un ou plus des brevets américains énumérés à http://www.sun.com/patents et un ou les brevets plus supplémentaires ou les applications de brevet en attente dans les Etats - Unis et dans les autres pays.

Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l'utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, parquelque moyen que ce soit, sans l'autorisation préalable et écrite de Sun et de ses bailleurs de licence, s'il y ena.

Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun.

Sun, Sun Microsystems, le logo Sun, Java, iPlanet et le logo iPlanet sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.

Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits protant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.

UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et licenciée exlusivement par X/Open Company, Ltd.

Acquisitions Fédérales: progiciel – Les organisations gouvernementales sont sujettes aux conditions et termes standards d'utilisation.

LA DOCUMENTATION EST FOURNIE “EN L'ÉTAT” ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFAÇON.

Contents

List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

List of Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Product Name Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Audience for This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Organization of This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Text Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Syntax Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Other Documentation Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

iPlanet Integration Server Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Documentation Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

iIS Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Viewing and Searching PDF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 1 Introduction: iIS Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

What Is an iIS Process Engine? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Multiple Engine Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

iIS Process Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Minimal Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Failover Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Full Configuration: Failover and Load Balancing Combined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

What Does an iIS Process Engine Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

iIS Process Management Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Setting up and Maintaining an iIS System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Setting Up an iPlanet UDS Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Installing iIS Process Management Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Setting Up and Maintaining Central Development Repositories . . . . . . . . . . . . . . . . . . . . . . . . . 38

iIS Process Management Tasks (continued)

Managing iIS Process Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Managing Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

iIS Process Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Conductor Script Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Custom System Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Repository Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Dump/Restore Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 2 Setting Up an iIS Process Management System . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Preparation: Setting up an iPlanet UDS Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

iIS Process System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

iIS Backbone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

iIS Process System Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Compiled and Interpreted Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

iIS Process System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Setting Up an iIS Process System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

iIS Process System Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

The iIS Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Central Server Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Engine Server Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Development Client Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Runtime Client Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Configuring and Starting Your iIS Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Maintaining an iIS Process System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Adding New Nodes to an iIS System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Moving an iIS Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Creating a New iIS Repository Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Moving an iIS Repository Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Creating a Private iIS Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Upgrading an iIS System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Uninstalling an iIS System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 3 The iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Starting the iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Using the cconsole Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4 iPlanet Integration Server • Process System Guide • August 2001

The iIS Console Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Main Viewing Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Mouse Popup Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Setting Password Protection for iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Exiting iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Using iIS Console Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Using the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Window Refresh Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Filtering iIS Console Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Specifying Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Example Filter Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Sorting iIS Console Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Using List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

iIS Console Main Window Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Environment Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Engine Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Monitor Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 4 Managing Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Production Engines Versus Development Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Configuring an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Engine Component Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Engine Startup Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Engine Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Customizing Engine Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

How to Configure a New Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Duplicating an Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Deleting an Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Starting an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Governor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Engine Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Primary Engine Unit Startup Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Database Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

How to Start an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Reconfiguring an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

How to Reconfigure an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

How to Dynamically Modify Database Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

How to Tune Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Monitoring and Changing Engine States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Monitoring Engines and Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Monitoring the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Monitoring Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Changing Engine States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Changing Engine Unit States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

About Recovering State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Shutting Down Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Managing an Engine Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Database Management Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Growth of the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Failure of the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Recovering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Dumping and Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Dumping Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Restoring Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Dump/Restore Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Chapter 5 Managing Registrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

About Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

What Does Registration Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Registration in Production Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

What Does Unregistration Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Engine Registration Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

About Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Registering iIS Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Registration Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Performing Registrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Upgrading Registrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Unregistering iIS Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Registering Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Unregistering Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Viewing Registrations for an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Unregistering a Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Monitoring Instances of a Registered Process Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Performing Application Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Monolithic Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Rolling Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

6 iPlanet Integration Server • Process System Guide • August 2001

Chapter 6 Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Engine Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Disrupted Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Explicitly Suspended Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Explicitly Terminated Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Activity States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Activity Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Process Instance Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Process Instance Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Activity Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Activity Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Activity Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Process Instance Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Completed Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Aborted Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Monitoring and Managing Engine Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Monitoring the State of a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Managing Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Suspending or Terminating Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Sending and Broadcasting Messages to Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Monitoring and Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Managing Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Checking the Status of a Process Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Aborting a Process Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Managing Activity Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Checking the Status of an Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Changing the State of an Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Managing Activity Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Checking the Status of an Activity Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Reprioritizing a Queued Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Managing Timer Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Checking the Status of a Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Changing the Timer State and Expiration Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Managing Process Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Checking the Value and Lock State of a Process Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Changing a Process Attribute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Removing a Process Attribute Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Checking for Bottlenecks in Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Analyzing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

History Log Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

State Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Monitoring and Managing Two-Phase Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Managing Two-Phase Commit Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Chapter 7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Process Engine Alarms Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Monitoring Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Viewing Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Engine Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

iIS Console Trace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Messages and Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Specifying Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

iIS Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Using the iIS Console Trace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Setting Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Special Example: Write Client Messages to Trace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

iIS Console Engine Event Filter Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Engine Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Using the iIS Console Engine Event Filter Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Displaying All Engine Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Displaying Process Instance Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Filtering Engine Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Performance Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Viewing Performance Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Logging Performance Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Chapter 8 Using the Conductor Script Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Conductor Script Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Starting Conductor Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Using the Cscript Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Working with Conductor Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

General Conductor Script Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Writing and Executing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Operating System and File Management Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Managing iIS Process Engines with Conductor Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Starting an Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Starting Individual Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Example Manual Startup Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

8 iPlanet Integration Server • Process System Guide • August 2001

Managing iIS Process Engines with Conductor Script (continued)

Monitoring Engines and Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Monitoring the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Monitoring Individual Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Changing Engine States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Changing Engine Unit States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Shutting Down Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Managing Registrations with Conductor Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Making iIS Library Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Registering iIS Library Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Unregistering iIS Library Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Managing Process Execution with Conductor Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Monitoring and Managing Engine Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Monitoring and Managing Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Managing Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Managing Activity Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Managing Activity Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Managing Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Managing Process Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Checking for Bottlenecks in Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Monitoring and Managing Two-Phase Commit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Monitoring Two-Phase Commit Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Managing Two-Phase Commit Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Appendix A Conductor Script Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Conductor Script Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Environment Mode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Engine Mode Commands: Engine Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Engine Mode Commands: Process Execution Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Component Mode Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Generic component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Engine Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Conductor Script Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

AbortActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

AbortAllProcesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

AbortProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

BroadcastMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

CommitTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

CompleteActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

ConsultActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

CreateActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Conductor Script Commands (continued)

CreateFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Event Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Object Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Object Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

DelegateActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

DeleteFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

FindDBService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

FindEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

FindGovernor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

FindNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

FindParentEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

FindPrimary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

FindUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

FlushLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

IIOPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

ListActivities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

ListActivityQueues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

ListConductorDistributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

ListEngines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

ListFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

ListProcesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

ListRegistrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

ListSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

ListTimers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

ListTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

MakeConductorDistribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

ModLogFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

ReadyActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

RegisterAlias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

RegisterAssignmentRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

RegisterProcessDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

RegisterUserProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

RegisterValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

RemoveReadLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

10 iPlanet Integration Server • Process System Guide • August 2001

Conductor Script Commands (continued)

RemoveWriteLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

RollbackActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

RollbackTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

SendMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

SetAttributeValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

SetPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

SetPrimary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

SetQueuedActivityPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

SetState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

SetTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

SetTimerDeadline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

SetTimerElapsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

ShowActivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

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

UnRegisterUserProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

WaitForStartup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Appendix B Engine Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Database Tables by Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Alphabetical Listing of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Database Schema Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Current State Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Registration Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

History Log Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

State Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

12 iPlanet Integration Server • Process System Guide • August 2001

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 . . . . . . . . . . . . . . . . . . . 35

Figure 1-5 Engine Manager Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Figure 2-1 Components of an iIS Process System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Figure 2-2 iIS Process System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Figure 3-1 iIS Console Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Figure 3-2 iIS Console Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Figure 4-1 Engine Configuration with both Failover and Load Balancing . . . . . . . . . . . . . . . . . . . 86

Figure 4-2 Typical Engine Partitioning Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Figure 5-1 Registration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Figure 5-2 Subprocess Activity References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Figure 6-1 Activity State Transitions—from Creation to Termination . . . . . . . . . . . . . . . . . . . . . . 164

Figure 6-2 Process Execution Objects: Properties and Relationships . . . . . . . . . . . . . . . . . . . . . . . 180

Figure 6-3 Client Applications Change Both iIS Process State and Application Data . . . . . . . . . 200

Figure 7-1 Specifying iPlanet UDS Message Output Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Figure A-1 Hierarchy of Conductor Script Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

14 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

To add a new node to an iIS system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

To create a new iIS Repository Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

To move an iIS Repository Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

To create a private iIS Repository on a development node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

To start the iIS Console on Windows or Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

To start the iIS Console on UNIX, OpenVMS, or Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

To set a password for iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

To turn automatic refresh off or on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

To set the automatic refresh interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

To force an immediate refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

To configure a new engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

To duplicate an engine configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

To delete an engine configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

To start an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

To start individual engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

To reconfigure an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

To modify database logging for an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

To check the engine runtime configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

To monitor individual engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

To change the state of an engine unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

To put the primary engine unit on STANDBY and the backup unit ONLINE . . . . . . . . . . . . . . . . . . 122

To use the Dump/Restore application to dump database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

To preserve custom engine database schema changes when upgrading iIS . . . . . . . . . . . . . . . . . . . . 132

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 . . . . . . . . . . . . . . . . . 148

To register an alias using the iIS Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

To unregister an alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

To view the registrations for a given engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

To unregister a registered distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

To monitor instances of a registered process definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

To perform a monolithic upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

To perform a rolling upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

To obtain state information about a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

To suspend a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

To terminate a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

To send a message to an active session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

To broadcast a message to all sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

To check the current execution status of a process instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

To abort a process instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

To change the state of an activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

To view the contents of an activity queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

To reprioritize a queued activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

To change the state and expiration time of a timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

To change the value of a process attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

To remove a process attribute lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

To find a process bottleneck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

To register an engine with the alarm service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

To unregister an engine from the Alarm service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

To filter alarms in the Process Engine Alarms window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

To search for an alarm in the Process Engine Alarms window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

To get detailed information about an alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

To remove an alarm from the Alarm window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

To view an engine component log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

To open the iIS Console Trace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

To set message filters for a selected engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

To set the engine tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

To open the Engine Event Filter window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

To view all engine events for the selected engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

16 iPlanet Integration Server • Process System Guide • August 2001

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

To log performance information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

To stop logging performance information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

To start Conductor Script on Windows or Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

To start Conductor Script on UNIX, OpenVMS, or Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

To start an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

To start an engine where delays might be involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

To start an individual engine component (governor, database service, or engine unit) . . . . . . . . . . 236

To check the engine runtime configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

To monitor individual engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

To change the state of an engine unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

To make an iIS library distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

To register an iIS distribution with an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

To unregister an iIS distribution from an engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

To obtain state information about a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

To suspend or terminate a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

To send a message to one or more sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

To check the status of a process instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

To abort a process instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

To check the status of an activity instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

To change the state of an activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

To list the contents of an activity queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

To reprioritize an activity in a queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

To check the status of a timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

To change the state of a timer or change its expiration time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

To check the value or lock state of a process attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

To change the value of a process attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

To remove an attribute lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

To find a process bottleneck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

To resolve transactions after a client or engine failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

List of Procedures 17

18 iPlanet Integration Server • Process System Guide • August 2001

Preface

The iIS Process System Guide describes how to manage a process system, one of the two subsystems that comprise iIS. The guide provides the system management principles and concepts upon which a process system is based, and describes how to perform process system management tasks.

This preface contains the following sections:

• “Product Name Change” on page 19

• “Audience for This Guide” on page 20

• “Organization of This Guide” on page 20

• “Text Conventions” on page 21

• “Other Documentation Resources” on page 22

• “iIS Example Programs” on page 24

• “Viewing and Searching PDF Files” on page 24

Product Name Change

Forte Fusion has been renamed the iPlanet Integration Server. You will see full references to the new name, as well as the abbreviation iIS.

Audience for This Guide

This book assumes familiarity with the basic concepts underlying an iIS process system. A discussion of these concepts and a description of iIS process system components, the functions they perform, and how they interact with an iIS Backbone can be found in the iIS Conceptual Overview. Additionally, information about creating and defining business process for use within an iIS process system can be found in the first two chapters of the iIS Process Development Guide.

Because an iIS system is built and distributed in an iPlanet UDS environment, it is helpful to understand iPlanet UDS system management concepts. For details, see the iPlanet UDS System Management Guide.

Organization of This Guide

The following table briefly describes the contents of each chapter:

Chapter Description

Chapter 1, “Introduction: iIS Process Management”

Chapter 2, “Setting Up an iIS Process Management System”

Chapter 3, “The iIS Console” Introduces the iIS Console, an interactive system

Chapter 4, “Managing Engines” Explains how to configure, start up, and manage an

Chapter 5, “Managing Registrations”

Chapter 6, “Managing Process Execution”

Chapter 7, “Troubleshooting” Explains tools and techniques used for diagnosing

Provides a brief introduction to the iIS process engine and process system management.

Describes the components of an iIS process system and how to distribute them among the different nodes in your environment.

management tool.

iIS process engine and its components.

Describes the registration process by which process definitions and other development components are made available for execution by a running engine.

Explains how an engine executes process definitions and how to monitor and make adjustments to process execution.

problems in process execution.

20 iPlanet Integration Server • Process System Guide • August 2001

Chapter Description

Text Conventions

Chapter 8, “Using the Conductor Script Utility”

Appendix A, “Conductor Script Commands”

Appendix B, “Engine Database Schema”

Text Conventions

This section provides information about the conventions used in this document.

Format Description

italics Italicized text is used to designate a document title, for

monospace Monospace text represents example code, commands that you

Explains how to perform iIS system management tasks using Conductor Script commands.

Provides a command reference for Conductor Script, a command line tool for process system management.

Provides a reference for the iIS process engine database schema.

emphasis, or for a word or phrase being introduced.

enter on the command line, directory, file, or path names, error message text, class names, method names (including all elements in the signature), package names, reserved words, and URLs.

ALL CAPS Text in all capitals represents environment variables

(FORTE_ROOT) or acronyms (iIS, JSP, iMQ).

Uppercase text can also represent a constant. Type uppercase text exactly as shown.

Key+Key Simultaneous keystrokes are joined with a plus sign: Ctrl+A

means press both keys simultaneously.

Key-Key Consecutive keystrokes are joined with a hyphen: Esc-S

means press the Esc key, release it, then press the S key.

Preface 21

Other Documentation Resources

iPlanet Integration Server Documentation

iIS Adapter Development Guide

iIS Backbone Integration Guide

iIS Backbone System Guide

iIS Conceptual Overview

iIS Installation Guide

iIS Process Client Programming Guide

iIS Process Development Guide

iIS Process System Guide

Online Help

When you are using an iIS development application, press the F1 key or use the Help menu to display online help. The help files are also available at the following location in your iIS distribution:

When you are using a script utility, such as FNscript or Cscript, type help from the script shell for a description of all commands, or help specific command.

FORTE_ROOT/userapp/forte/cln/*.hlp.

<command> for help on a

Documentation Roadmap

A roadmap to the iIS documentation can be found in the iIS Conceptual Overview manual.

Preface 23

iIS Example Programs

iIS example programs are shipped with the iIS product and installed in two locations, one for process development (using the process engine) and one for application integration (using the iIS backbone).

Process Development Examples Process development examples are installed at the following location:

FORTE_ROOT/install/examples/conductr

The PDF file, c_examp.pdf, describes how to install and run the examples in this directory. The Appendix to the iIS Process Development Guide also describes how to install and run the examples.

Application Integration Examples Process integration examples are installed at the following location:

FORTE_ROOT/install/examples/fusion

Each example has its own sub-directory, which contains a README file that explains how to install and run the example.

Viewing and Searching PDF Files

You can view and search iIS documentation PDF files directly from the documentation CD-ROM, store them locally on your computer, or store them on a server for multiuser network access.

NOTE You need Acrobat Reader 4.0+ to view and print the files. Acrobat

Reader with Search is recommended and is available as a free download from http://www.adobe.com. If you do not use Acrobat Reader with Search, you can only view and print files; you cannot search across the collection of files.

➤ To copy the documentation to a client or server

1. Copy the doc directory and its contents from the CD-ROM to the client or

server hard disk.

You can specify any convenient location for the not dependent on the iIS distribution. You may want to consolidate your iIS documentation with the documentation for your iPlanet UDS distribution.

doc directory; the location is

24 iPlanet Integration Server • Process System Guide • August 2001

Viewing and Searching PDF Files

2. Set up a directory structure that keeps the iisdoc.pdf and the iis directory in

the same relative location.

The directory structure must be preserved to use the Acrobat search feature.

NOTE To uninstall the documentation, delete the

doc directory.

➤ To view and search the documentation

1. Open the file iisdoc.pdf, located in the doc directory.

2. Click the Search button at the bottom of the page or select Edit > Search >

Query.

3. Enter the word or text string you are looking for in the Find Results Containing

Text field of the Adobe Acrobat Search dialog box, and click Search.

A Search Results window displays the documents that contain the desired text. If more than one document from the collection contains the desired text, they are ranked for relevancy.

NOTE For details on how to expand or limit a search query using

wild-card characters and operators, see the Adobe Acrobat Help.

4. Click the document title with the highest relevance (usually the first one in the

list or with a solid-filled icon) to display the document.

All occurrences of the word or phrase on a page are highlighted.

Preface 25

Viewing and Searching PDF Files

5. Click the buttons on the Acrobat Reader toolbar or use shortcut keys to

navigate through the search results, as shown in the following table:

Toolbar Button Keyboard Command

Next Highlight Ctrl+]

Previous Highlight Ctrl+[

Next Document Ctrl+Shift+]

To return to the

iisdoc.pdf file, click the Homepage bookmark at the top of

the bookmarks list.

6. To revisit the query results, click the Results button at the bottom of the

iisdoc.pdf home page or select Edit > Search > Results.

26 iPlanet Integration Server • Process System Guide • August 2001

Chapter 1

Introduction: iIS Process

Management

iIS process system management is largely devoted to managing iIS process engines and the functions they perform.

This chapter provides a high level description of what an iIS process engine is and what it does. It describes the relationship of the engine to other parts of the iIS system and describes its component parts.

This chapter also discusses the tasks required of system managers and the tools they use to perform these tasks.

What Is an iIS Process Engine?

An iIS process engine is the heart of an iIS system, shown in Figure 1-1 on page 30, reproduced from the iIS Process Development Guide.

The engine controls and manages business processes from beginning to end, coordinating the work of the different resources that perform the activities defined in each process instance.

At each stage of a process’s execution, the engine evaluates whether an activity is ready to be performed and, if so, assigns that activity to the appropriate resources. When an activity is completed, the engine routes the work to the next activity or set of activities.

The engine knows how to manage the flow of a process because it is programmed to control and track that process. The program that the engine executes is an iIS process definition. The process definition is created in the iIS Process Definition Workshop and is then registered with the engine. For information on process definitions, see the iIS Process Development Guide.

What Is an iIS Process Engine?

Once a process definition has been registered with the engine, an iIS process client application (or an application proxy—see Figure 1-1 on page 30) can open a session with the engine and create an instance of the process. The client application or proxy provides any data required to start the process instance, and then the engine takes over. It assigns activities directly to engine sessions or to queues where they can be accessed. Client applications—or applications interacting with the engine through proxies—perform the work required of each activity using whatever application services, enterprise data, or desktop applications necessary, and then notify the engine that the activity has been completed. For information on client applications, see the iIS Process Client Programming Guide. For information about proxies, see the iIS Backbone System Guide.

The relationship of the engine to iIS process client applications, on the one hand, and to the process development workshops, on the other, is illustrated in

Figure 1-1 on page 30. Client applications maintain sessions with an iIS process

engine to initiate a business process or perform its activities in it. The engine can service a very large number of sessions and manage many instances of many different process definitions. As process definitions (as well as assignment rule dictionaries, user profiles, and a validation) are created or modified in the iIS development environment, they can be registered with the engine, and become the basis for further process execution.

The engine is thus central to an iIS system, implementing business processes that require the performance of many activities by many resources.

28 iPlanet Integration Server • Process System Guide • August 2001

What Is an iIS Process Engine?

Multiple Engine Systems

An iIS system does not need to be limited to a single engine. It can have any number of engines. For example, one engine might be used for testing and another used for production. (see “Production Engines Versus Development Engines” on

page 83.)

In other cases, organizational considerations or heavy load conditions might require multiple production engines. While engines can communicate with one another—a processes definition that executes on one engine can be invoked as a subprocess by a process definition executing on another—each engine operates independently. A single instance of a process definition executes on only one engine.

In most cases, different process definitions would be executed on different engines. For example, one process might execute on one engine while a subprocess it invokes might execute on another. If the same process definition is executed on more than one engine (to handle the workload of a large number of client users) then client users would normally be divided up between the engines, each user logging in to only one of the engines.

Multiple engines can run in a single iPlanet UDS environment, or can be spread across a number of connected iPlanet UDS environments. However, there is no mechanism by which one engine can fail over to another. iIS uses a different mechanism to handle engine failover (see “Failover Configuration” on page 33).

Chapter 1 Introduction: iIS Process Management 29

What Is an iIS Process Engine?

Figure 1-1 An iIS Process Management System

Process Develpment Workshops

System Management Tools

Registration

Process Engines

Central

Development

Repository

Organization

Database

Client Applications

TOOL

C++

CORBA/IIOP

ActiveX

JAVA

Application

Services

Engine

Database

Engine

Enterprise

Database

Databases

30 iPlanet Integration Server • Process System Guide • August 2001

iIS Process Engine Components

As mentioned earlier in this chapter, an iIS process engine is the heart of an iIS system and has been designed to support mission-critical production application systems. The iIS process engine maintains performance under heavy and/or increasing loads and provides automatic recovery in case of unanticipated system failure.

To support both failover and load balancing, the iIS process engine is engineered as a set of interacting application components. These applications work together to provide engine failover protection and the flexibility to handle increasing loads. An iIS engine generally consists of the following application components:

• two engine units

• an engine governor

• a number of database access services

An iIS engine also includes a database that provides storage for persistent state information.

iIS Process Engine Components

The various engine components are described below in relation to their role in providing failover and load balancing capability. A minimal engine configuration is discussed first, followed by failover and load balancing configurations. To create these configurations, see “Configuring an Engine” on page 85.

Minimal Engine Configuration

An iIS process engine consists minimally of three components—an engine unit, a database service, and a database—as shown in Figure 1-2. In this configuration, the engine provides basic functions without failover or load balancing capabilities.

Chapter 1 Introduction: iIS Process Management 31

iIS Process Engine Components

Figure 1-2 Minimal Engine Configuration

Client Applications

Primary

Engine

Unit

iIS Process Engine

Database

Service

Engine

Database

Engine Unit The engine unit is an application that performs all the basic iIS engine functions (see “What Does an iIS Process Engine Do?” on page 36). The engine unit is a single iPlanet UDS server partition containing a number of manager objects (see Figure 1-5 on page 37). The engine unit, in performing its work, tracks the state of each process, activity, timer, process attribute lock, and session that it creates in the course of process execution. In a typical production situation, the engine unit maintains state information on tens of thousands to millions of objects. It is critical that this state information be kept in a persistent form should the engine unit fail and need to be recovered. For this reason, the engine unit writes all current state information to the engine database (described below).

Database Service The database service is an application that manages the engine unit’s database access. The database service is a single iPlanet UDS server partition that maintains communication channels with the engine unit, opens a session with the engine database, and writes and retrieves state information as required by the engine unit. The database service is a single–threaded application, and can handle only one request to the database at a time. (To see how to overcome this limitation, see “Full Configuration: Failover and Load Balancing Combined” on page 35.)

Engine Database The engine database provides persistent storage for state information maintained by the engine. It also stores registration information regarding all process definitions, assignment rule libraries, user profiles, and validations that can be executed by the engine. In addition, the engine database can be used to log historical information for tracking process execution over time. The

32 iPlanet Integration Server • Process System Guide • August 2001

iIS Process Engine Components

engine database is not supplied by the iIS product and must be set up independently; however, the engine unit can create all required database tables at startup time. The iIS process engine supports all relational database systems supported by iPlanet UDS (for example, Sybase, Oracle, Informix, and so on).

Failover Configuration

To provide for failover in case the engine unit fails (for whatever reason), a backup engine unit and governor are added to the iIS process engine configuration, as illustrated in Figure 1-3.

Figure 1-3 Engine Configuration with Failover

iIS Process Engine

Client Applications

Governor

Primary

Engine

Unit

Database

Service

Backup

Engine

Unit

Engine

Database

Backup Engine Unit The backup engine unit, a replicate of the engine unit partition, has a unique name that distinguishes it from the primary engine unit. The primary and backup engine units are partners. The backup engine unit runs in a standby state when the primary engine unit is on line. The two partners know about each other through an open communication channel. If the primary engine unit fails, the backup engine unit comes on line. In that case, the database service

Chapter 1 Introduction: iIS Process Management 33

iIS Process Engine Components

opens a channel to the backup unit, which takes over by recovering all the persistent state information stored in the engine database. The new primary engine unit starts process execution at the point where the old primary engine unit left it. Client sessions with the engine are maintained throughout this failover transition.

NOTE Failover (and recovery of state information) is not instantaneous. In

Governor The governor is an application that assists in deciding when failover should occur. The governor maintains an open communication channel with both the primary and backup engine units. It uses these channels to determine if a closing of the communication channel between primary and backup engine units is due to engine unit failure or network failure. For example, if the communication channel between the primary and backup engine units closes, but the governor’s communication channel with the primary engine unit remains open, the governor assumes the primary engine unit is still online. However, if neither the governor nor backup engine unit can communicate with the primary engine unit, the governor assumes the primary engine unit has failed, and places the backup engine unit online, making it the new primary engine unit.

a production system, the state information stored in the engine database can be quite extensive. It includes information on the state of every process instance, the state of every activity and timer in each process instance, the values of process attributes and their lock states, the state of routers and triggers for each activity instance, session activity lists, queue lists, and so on. Accordingly, the amount of time for failover to occur is dependent on the amount of state information in the database and the speed of database access.

(If the primary engine unit has not failed, but cannot communicate with either the governor or backup engine unit, the primary engine unit will drop into STANDBY state, since it has no way of knowing the state of its partner.)

34 iPlanet Integration Server • Process System Guide • August 2001

iIS Process Engine Components

Full Configuration: Failover and Load Balancing Combined

To deal with heavy loads on the engine and overcome the potential bottleneck of a single database service, additional database services can be added to the failover engine configuration, as illustrated in Figure 1-4.

With a heavily loaded engine, large numbers of state changes need to be written to the engine database simultaneously. Database access is likely to be a performance problem. To accommodate large loads, database access is shared among a set of database service components (which may be running on different nodes) using a database service router in the primary engine unit.

Each service is assigned a unique name and allocated a priority (depending, perhaps, on its host node—see “Engine Component Partitioning” on page 85). When the engine unit needs to access the database, the router provides it the highest priority database access service available. If there are a number of services of equal priority available, the router chooses a database service on a round-robin basis, thus sharing the load among all available services.

Figure 1-4 Engine Configuration with Both Failover and Load Balancing

iIS Process

Client Applications

Engine

Primary

Engine

Unit

Router

Database

Services

Database

Services

Governor

Backup

Engine

Unit

Engine

Database

Chapter 1 Introduction: iIS Process Management 35

What Does an iIS Process Engine Do?

As suggested in “What Is an iIS Process Engine?” on page 27, an iIS process engine performs a number of different functions in support of an iIS system. These include the following.

Managing sessions The engine opens, suspends, and closes sessions. When opening a session, the engine first validates a user’s logon against an organizational database. For more information on sessions, see “Engine Sessions”

on page 158.

Executing processes The engine creates instances of a process and manages their execution from start to finish. During each process’ execution, a succession of activities is performed by applications that have opened sessions with the engine. The engine manages and tracks these activities through to their final completion.

Registering distributions Process definitions, assignment rule dictionaries, user profiles, and a validation constitute the process logic components executed by the engine during process execution. Registration lets you change these components dynamically as business processes and organizational structures change.

Maintaining an engine history database The engine can maintain a history of each process execution, writing all changes of state to an engine history database. The history can include changes of state in activities, process attributes, timers, and so on.

While process execution is the key engine function, managing sessions, registering definitions, and maintaining the history database are all necessary to support process execution.

To provide these functions, the iIS engine is internally structured around a number of manager objects, as shown in Figure 1-5:

• Session Manager—maintains engine sessions

• Process Manager—works closely with the Timer Manager and Access Manger

to execute iIS process definitions

• Registration Manager—keeps track of the names and versions of registered process definitions

• History Manager—writes current state and history log information to the engine database.

36 iPlanet Integration Server • Process System Guide • August 2001

Figure 1-5 Engine Manager Objects

iIS Process Management Tasks

Engine Unit

Session

Manager

Process

Manager

Timer

Manager

Engine

Object

Access

Manager

iIS Process Management Tasks

iIS process management tasks can be grouped into four broad categories:

Registration

Manager

History

Manager

Database

Service

• setting up and maintaining an iIS process system

• managing iIS process engines

• managing registration of process definitions

• managing process execution

Each of these categories is discussed briefly below and treated in detail in the corresponding chapter of this system management guide.

Setting up and Maintaining an iIS System

Setting up a new iIS process management system—whether used for development, testing, production, or a combination of the three—involves a number of basic tasks, described below.

Chapter 1 Introduction: iIS Process Management 37

iIS Process Management Tasks

Setting Up an iPlanet UDS Runtime Environment

An iIS process management system runs in an iPlanet UDS software environment. Both the development and production capabilities of iIS (both process development and process execution) use the distributed runtime services provided by an iPlanet UDS environment. A functioning iPlanet UDS environment is the technical infrastructure underlying an iIS process management system.

Installing iIS Process Management Software

iIS process management system software consists of a number of client and server software modules required to support nodes that perform a number of different functions. The functionally different types of nodes in an iIS process system are the following:

• nodes that support iIS process engine components

• nodes that support process development

• nodes that support client application development or client application

execution in a production environment

Before installing iIS process system software, you must first determine which nodes in your iPlanet UDS environment are used for each of these purposes and to install the corresponding system software on each.

When upgrading iIS process system software, especially in production environments, you might have to migrate data from existing iIS process engine databases to new ones. See “Upgrading an iIS System” on page 63.

Setting Up and Maintaining Central Development Repositories

In iIS development environments, the code created in the process development workshops is stored in a modified iPlanet UDS central development repository. As an iIS system manager, you may be called on to create iIS central development repositories and start a Repository Server for each. (Developers can also use private iIS repositories.)

Central development repositories require maintenance, such as backing them up periodically, compacting them regularly, and implementing usage patterns among your development staff that improves performance.

For more information on managing central development repositories, see the iPlanet UDS System Management Guide.

38 iPlanet Integration Server • Process System Guide • August 2001

iIS Process Management Tasks

Managing iIS Process Engines

Care must be taken to make sure that each iIS process engine is set up and performing properly. Managing engines consists of the following tasks:

• configuring engines

• starting up and shutting down engine components

• monitoring and changing the state of an engine

• reconfiguring an engine to accommodate increased load, improve

performance, or recover from failure

• managing engine databases

Managing Registration

An iIS process engine executes process logic created in the process development workshops: process definitions, assignment rule dictionaries, and a user profile. These software components need to be registered with the engine so they can be dynamically loaded by the engine and used in process execution.

As a system manager, you have to regularly register new or updated process definitions (or assignment rule dictionaries or a user profile) with an engine, and possibly unregister them when they become obsolete.

Managing Process Execution

In executing process definitions, the engine creates instances of each process definition and coordinates their execution from start to finish. During process execution, a succession of activities specified by the process definition is performed by client application that have opened sessions with the engine. The engine manages and tracks these activities through to their final completion, ensuring that they are performed in proper sequence.

Chapter 1 Introduction: iIS Process Management 39

iIS Process Management Tools

Managing process execution involves monitoring the activity of the engine and making administrative adjustments when necessary. The specific tasks include:

• monitoring engine sessions, and suspending or terminating sessions when necessary

• monitoring the number of process instances being executed by an engine at any time

• monitoring execution of individual processes, looking for bottlenecks or failures, and aborting or resetting particular process activities, as necessary

• providing historical analysis of process execution activity

iIS Process Management Tools

iIS includes two system management tools: the iIS Console and its command line counterpart, Conductor Script. These tools provide an interface to system management agents in the iPlanet UDS runtime environment and in the iIS process engine for managing engines and process execution.

iPlanet UDS also provides a separate set of command-line tools for managing development repositories.

This section briefly describes the iIS process management tools.

iIS Console

The iIS Console application provides a graphical user interface for performing most of the system management tasks discussed in “iIS Process Management

Tasks” on page 37. You use the iIS Console to manage iIS engines (including

registering process definitions, and so on), manage individual process instances, and monitor overall process execution activity.

Most system management procedures explained in this guide assume that you are using the iIS Console. For an introduction to the iIS Console, see Chapter 3, “The

iIS Console.”

40 iPlanet Integration Server • Process System Guide • August 2001

iIS Process Management Tools

Conductor Script Utility

The Conductor Script utility is the functional equivalent of the iIS Console application, but with a command-line interface. You can perform any of the functions using Conductor Script commands that you can perform in the iIS Console, but you can also incorporate these functions into scripts for execution at specified times.

For more information on the Conductor Script utility, see Chapter 8, “Using the

Conductor Script Utility.”

Custom System Management Tools

In an iPlanet UDS development environment you can use the iPlanet UDS development workshops to write your own system management tools exercising the same system management agents utilized by the iIS Console and the Conductor Script utility. These custom tools allow you to automate regular system management tasks or respond automatically to particular state conditions in an engine.

Repository Management Tools

iPlanet UDS provides several command-line tools for creating (rpcreate), copying

rpcopy), starting (rpstart), stopping (rpstop), and compacting (rpclean) central

( development repositories and Repository Servers.

For more information on repository management tools, see the iPlanet UDS System Management Guide.

Dump/Restore Facilities

iIS provides facilities for dumping the information in an engine database to an ASCII file. These facilities—a Dump/Restore graphical user interface application and an equivalent command-line utility—are used to restore an engine database in iIS upgrades in which the engine database schema is changed. For more information on the Dump/Restore utilities, see “Dumping and Restoring Data” on

page 126.

Chapter 1 Introduction: iIS Process Management 41

iIS Process Management Tools

42 iPlanet Integration Server • Process System Guide • August 2001

Chapter 2

Setting Up an iIS Process

Management System

Setting up an iIS process management system—whether for development, testing, production, or a combination of the three—is the first task you must perform as an iIS process system manager.

System setup involves determining which nodes in your environment support the different components of your iIS process system, and then installing the appropriate iIS software on each of these nodes.

Since iIS runs on top of a functioning iPlanet UDS environment, you may have to set up an iPlanet UDS environment before setting up your iIS process system.

This chapter explains how to set up an iIS process system, and covers the following topics:

• setting up an iPlanet UDS runtime environment

• components of an iIS process system

• setting up an iIS process system

• maintaining an iIS process system

For information on how to configure and start an iIS process engine, refer to

Chapter 4, “Managing Engines.”

Preparation: Setting up an iPlanet UDS Runtime Environment

An iIS process system runs in an iPlanet UDS software environment. Both the development and runtime capabilities of iIS (process development and process execution) use the distributed runtime services provided by an iPlanet UDS environment. A functioning iPlanet UDS runtime system (including a central development repository for iIS process development) is the technical infrastructure underlying an iIS process system.

Consequently, you must have a functioning iPlanet UDS environment before setting up an iIS process system. This section introduces some of the important considerations for setting up an iPlanet UDS environment. For detailed information on how to set up an iPlanet UDS environment, consult the iPlanet UDS System Management Guide.

iPlanet UDS system software is designed to be environment independent. Nevertheless, iPlanet UDS software has critical dependencies on the specific versions of operating systems, window systems, networking systems, runtime libraries, and database management systems used at your site. One of the most important aspects of properly setting up an iPlanet UDS environment is to make sure that the physical environment (hardware and software) meets iPlanet UDS system requirements. For more information on these requirements, see the iPlanet UDS System Installation Guide.

While iPlanet UDS system software is usually installed in an existing network configuration, you should consider how to best use the available resources, depending on the type of environment you are setting up.

If the environment is principally an iPlanet UDS or iIS development environment, then the locations of your central development repositories (Repository Servers) and Environment Manager service are key considerations.

If the environment is principally a production environment for mission-critical applications, then the availability and locations of vital application resources (such as database management systems and C program libraries) and the speed and reliability of servers are some key considerations. These considerations might also influence where you place the Environment Manager service.

In general, when setting up an iPlanet UDS environment, you first install iPlanet UDS on a node that plays the role of a central server. Typically, this node hosts the Environment Manager service and the Repository Server and often serves as a central distribution node for installing iIS on other nodes in your environment. After you install iPlanet UDS on your central server, you install iPlanet UDS on other nodes in the environment.

44 iPlanet Integration Server • Process System Guide • August 2001

The iPlanet UDS installation program creates an iPlanet UDS directory structure and source files on your target node, sets a number of environment variables used by iPlanet UDS at startup time, and creates startup scripts for starting the appropriate system management service—the Environment Manager or Node Manager—for your target node.

Setting up an iIS process system, in turn, depends upon the iPlanet UDS system management services provided in an iPlanet UDS environment.

iIS Process System Components

An iIS process system consists of both development and runtime components, as illustrated in Figure 2-1, and described in the iIS Process Development Guide.

The system includes one or more iIS process engines, which are accessed by a number of iIS process client applications. An engine controls and manages the flow of business processes, coordinating the work of the different client applications that perform the activities that make up these processes. The client applications perform activities directly or by invoking other application services in a distributed application.

iIS Process System Components

An iIS process engine executes process definitions created by developers using a set of graphically-based process development workshops. These workshops store information in a central development repository. When development of a process definition is complete, the process definition is dynamically registered with an engine, which can then execute the process on behalf of a number of applications. These applications can be client applications that directly call the engine, or applications that are integrated using the iIS backbone.

Chapter 2 Setting Up an iIS Process Management System 45

iIS Process System Components

Figure 2-1 Components of an iIS Process System

Process Develpment Workshops

System Management Tools

Registration

iIS Process Engines

Primary

Engine

Unit

Central

Development

Repository

Organization

Database

Service

Database

Service

Engine

Database

Engine

Enterprise

Database

Databases

Client Applications

TOOL

C++

CORBA/IIOP

ActiveX

JAVA

Governor

Backup

Application

Services

The components of an iIS process system, shown in Figure 2-1, are implemented through a number of software modules running on various nodes in your computing environment. Some of the components are provided by iIS system software (iIS process engine components, process development workshops, and system management tools). Some must be developed on site and require iIS system software (process definitions and iIS process client applications). Others must be developed on-site using other software products (organization database).

46 iPlanet Integration Server • Process System Guide • August 2001

To set up an iIS process system, install the iIS system software modules that support development on your development nodes. Then install the iIS runtime modules on the nodes on which you will be executing your distributed enterprise applications.

iIS Backbone

If you are integrating applications with the iIS Backbone, also install the iIS runtime. For more information, refer to the iIS Installation Guide. For management functions specific to the iIS Backbone, refer to the iIS Backbone System Guide.

iIS Process System Software

iIS process system software consists of a number of software modules that provide—or are used to develop and manage—many of the iIS process system components illustrated in Figure 2-1 on page 46. These modules, organized by functional category, are described in the following table. The table also indicates which system software modules are marked for use as compiled partitions.

iIS Process System Software

Table 2-1 Process System Software Modules

Software Module Category Description

WFEngineUnit

(compiled)

WFGovernor

(compiled)

WFDatabaseSvc

(compiled)

Engine component

The server application that performs all the basic iIS engine functions (see “What Does an

iIS Process Engine Do?” on page 36). Consists

of a single iPlanet UDS server partition. Needed on engine server nodes.

The server application that assists in deciding when failover of an engine unit should occur (see “Governor” on page 105). Consists of a single iPlanet UDS server partition. Needed on engine server nodes.

The server application that manages the engine unit’s database access (see “Database

Service” on page 109). Consists of a single

iPlanet UDS server partition. Needed on engine server nodes.

Chapter 2 Setting Up an iIS Process Management System 47

iIS Process System Software

Table 2-1 Process System Software Modules (Continued)

Software Module Category Description

WFLibrary

(compiled)

WFModel

(compiled)

WFAccessServiceObj

(compiled)

WFClientLibrary

(compiled)

Process development

TOOL client application development

WFProcMgrLibrary TOOL client

application development

A library distribution that supports the process development workshops. Needed in iIS process development repository and on process development nodes.

A library distribution that provides repository schema definitions used to create code in the process development workshops. Needed in iIS process development repository and on process development nodes.

A library distribution that provides code used in the process development workshops for accessing iPlanet UDS service objects from within activity and router methods. Needed in iIS process development repository and on engine server nodes.

A library distribution that provides the API for process client applications written in the iPlanet UDS TOOL language. Needed in client application development repository, on TOOL client application development nodes, and on runtime nodes running client applications.

A library distribution that provides the limited process management API for process client applications written in the iPlanet UDS TOOL language. Optionally used in client application development repository, on TOOL client application development nodes, and on runtime nodes running such client applications.

WFAdminLibrary TOOL client

48 iPlanet Integration Server • Process System Guide • August 2001

application development

A library distribution that provides the limited process execution monitoring API for process client applications written in the iPlanet UDS TOOL language. Optionally used in client application development repository, on TOOL client application development nodes, and on runtime nodes running such client applications.

Table 2-1 Process System Software Modules (Continued)

Software Module Category Description

iIS Process System Software

WFClientAPI

(compiled)

WFCORBAapi

(compiled)

C++ client application development

Java/IIOP client application development

WFConsole System

Management

WFScript System

Management

WFDrWind Engine

Database Dump/Restore application

A DLL required to write process client application code in C++. Needed on C++ client application development nodes, and on runtime nodes running C++ client applications.

A server application (CORBA interface service) required to execute process client application code written in JAVA/IIOP. Needed on at least one server node in the iIS environment, normally the central server or an engine server.

A GUI client application for performing iIS process management system tasks. For details, see Chapter 3, “The iIS Console.”

A command-line client application for scripting iIS system management tasks. For details, see Chapter 8, “Using the Conductor

Script Utility.”

A graphical user interface application used for dumping engine database tables to a file and for restoring data to an engine database. For details, see “Dumping and Restoring Data” on

page 126.

WFDrDump Engine

Database Dump utility

WFDrRest Engine

Database Restore utility

OFCustomIF

System A library distribution that provides “interface

(compiled)

WFCustomIF

System Extension of OFCustomIF.

(compiled)

A standalone program that dumps the engine state and history data to files. For details, see

“Dumping Database Tables” on page 126.

A standalone program that restores the data from files generated using WFDrDump to an engine database. For details, see “Restoring

Database Tables” on page 131.

glue” between a client application, engine, and user profile. Needed in iIS development repositories, on engine server nodes, and on process client application development nodes.

Chapter 2 Setting Up an iIS Process Management System 49

iIS Process System Software

Table 2-1 Process System Software Modules (Continued)

Software Module Category Description

WFEnvDefinition

(compiled)

WFEnvAgent

(compiled)

en_us.cat System A message catalog used in translating all

WFSeed.btx WFSeed.btd

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. Needed on central server node.

language strings in the product.

Development workshops

A base development repository that contains all the class definitions needed to create process definitions or TOOL client applications. Needed on repository server nodes.

Compiled and Interpreted Engine Components

There is a script for alternating between the use of compiled or interpreted engine components. This is useful if exceptions occur when you are running an engine in compiled mode; you can switch to interpreted mode to obtain trace back on exceptions. The platform-specific script, which is installed in FORTE_ROOT/install/bin, is the following:

Script Name Platforms Types of Script

setccomp.sh All UNIX Bourne-shell

setccomp.bat MS Windows NT MS-DOS batch file

setccomp.com Alpha VMS, VAX/VMS VMS command procedure

Syntax:

setccomp.sh TRUE | FALSE

TRUE specifies compiled partitions; FALSE specifies interpreted partitions.

50 iPlanet Integration Server • Process System Guide • August 2001

iIS Process System Software

➤ Before you invoke the setccomp script, you must do the following

1. Set the FORTE_ROOT environment variable to point to a valid iIS installation.

2. Install the following iIS library distributions in the iPlanet UDS development

environment:

❍ WFGovernor

❍ WFEngineUnit

❍ WFDatabaseSvc

3. Start the iPlanet UDS Environment Manager on the server node where you

invoke the script.

iIS Process System Configuration

Setting up an iIS process system involves a bit of system design work. You must decide in advance, for example, which nodes in your computing environment host the various iIS process system components shown in Figure 2-1 on page 46.

In particular, you must decide which node or nodes in your environment support the following functions:

• running iIS process engine components

• developing process definitions

• developing iIS process client applications

• hosting iIS system management tools

• running the iIS central development Repository Server

• running iIS process client applications

All but the last of these functions require iIS process system software. In setting up an iIS process management system, these are the components that are the focus of attention.

For purposes of discussion, an example iIS process system configuration is shown in Figure 2-2 on page 53. Seven distinct kinds of iIS nodes are shown:

Central server The iPlanet UDS central server node in your environment. It hosts the iPlanet UDS Environment Manager (including Name Service) and one or more unique iIS services (such as the WFEnvAgent service).

Chapter 2 Setting Up an iIS Process Management System 51

iIS Process System Software

Repository server A server node (runs an iPlanet UDS Node Manager) that hosts the iIS central development repository and repository service.

Engine server A server node (runs an iPlanet UDS Node Manager) that hosts one or more engine components of one or more engines. One of the engine servers typically hosts an engine database. (Putting the engine database and the engine server on separate nodes is generally not recommended for performance reasons.)

Process development A node on which process developers (using the process development workshops) create the process definitions that are executed by iIS process engines.

Client application development A node on which client application developers create the process client applications that communicate with the iIS engine and perform the activities specified in process definitions.

System management A node used by a system manager to manage an iIS process system.

Runtime client A node that runs an iIS process client application, but which cannot be used for development.

While conceptually it is easier to think of each of these nodes as distinct, in reality there is no reason why some of the functions described could not be combined and performed on a single node. (In fact, you could run the whole system on a single node.)

For example, process development and client application development could both be performed on the same client node, or each could be performed on an engine server node that supports a windowing system. Deciding where these components are installed depends principally on who performs the various iIS development and system management tasks.

Also, the central server, which plays a unique role in an iIS system, can both host the central development repository and serve as an engine server node, supporting one or more iIS process engine components. Application servers in your iIS process system can also host iIS engine components. Choosing which components to install on which servers depends on the resources available on each server and the requirements of each component.

52 iPlanet Integration Server • Process System Guide • August 2001

Figure 2-2 iIS Process System Configuration

Process Development

iIS Process System Software

Central Server

Process

Development

Workshops

Client Application

Development

Client API

System Management

Tools

Conductor

Console

Runtime Applications

Environment

Manager

Repository Server

Repository

Service

Engine Server

Engine

Components

Application Servers

Central

Development

Repository

Engine

Database

You do not have to decide at iIS installation time exactly which engine components to assign to each server node because all component partitions are installed on each server node that supports an engine. You select which components to start on any node when you configure each engine (see “Configuring an Engine” on page 85).

Enterprise

Application

Services

Chapter 2 Setting Up an iIS Process Management System 53

Database

iIS Process System Software

For the purpose of system setup, the primary considerations are that the iIS process engine is the workhorse of your iIS process system and that it accesses a potentially very large database. Your engine server node or nodes should therefore be a very high performance server with plenty of available memory. If you are unsure at this point how to configure your iIS engine, designate all likely nodes as engine server nodes. This approach gives you the most flexibility later on.

Another design issue concerns the iIS development repository. You might want iIS developers to use an existing iPlanet UDS repository, or you might prefer to create one or more central development repositories for exclusive use by iIS developers. In addition, you might decide that the repository server needed to support iIS development should reside on a server other than the central server node hosting the Environment Manager, as shown in Figure 2-1 on page 46.

In any case, before beginning your iIS setup procedure, fill in a table similar to the one that follows:

iIS Function Node type: Server/Client Node Names

Central server Server

Repository server Server

Engine servers Server

Process development Client or server

Client application development

System management Client or server

Runtime client application Client or server

Client or server

54 iPlanet Integration Server • Process System Guide • August 2001

Setting Up an iIS Process System

After you have decided how to configure your iIS process system (and filled out the table in the previous section), you are ready to set up your system.

To set up an iIS process system, run the platform-specific iIS installation program on each node requiring iIS process system software. The software components installed by the program depend on whether the target node is a central server node, engine server node, client development node (process development or client application development), or runtime client.

Because the iIS installation program depends on services provided by an iPlanet UDS runtime system, you must set up a functioning iPlanet UDS runtime environment if you do not already have one at your site. (See “Preparation: Setting

up an iPlanet UDS Runtime Environment” on page 44.)

iIS Process System Setup Procedure

Setting Up an iIS Process System

The following general procedure should be followed in setting up an iIS process system.

➤ To set up an iIS process system

1. Make sure that you have a functioning iPlanet UDS environment that includes

all the server and client nodes required to support your iIS process system.

2. Run the iIS installation program on your iPlanet UDS central server node.

3. Run the iIS installation program on all iIS engine server nodes.

4. Run the iIS installation program on all iIS client nodes (process development

and/or client application development nodes).

5. On all development nodes, set the FORTE_REPOSNAME environment

variable to the name of your iIS Repository Server. (You can use the iPlanet UDS Control Panel—see the iPlanet UDS System Management Guide for more information.)

6. Configure and start your iIS process engine or engines. (See Chapter 4,

“Managing Engines.”)

Chapter 2 Setting Up an iIS Process Management System 55

Setting Up an iIS Process System

7. After process client applications have been developed, run the iIS installation

program on all runtime client nodes (those nodes that support an iIS process client application but do not support development).

8. In sites developing or running process client applications using the

CORBA/IIOP interface to the iIS engine, start the CORBA/IIOP interface service using the IIOPServer Conductor Script command (see “IIOPServer” on

page 287).

This setup procedure creates a functioning iIS process system in which developers can create process definitions and register them with an iIS engine and then develop process client applications and use them to perform the activities of an executing process instance.

CAUTION An iIS process system can only function in the iPlanet UDS

environment in which it has been set up. For example, you cannot change the name of your iPlanet UDS environment—even if the physical environment remains the same—and still have a functioning iIS process system.

The iIS Installation Program

The setup procedure described in the previous section makes extensive use of the iIS installation program. The iIS installation program has four main installation options: central server node, engine server node, development client node, and runtime client node. Each installs, by default, the iIS system software appropriate for that type of node, and provides customizing options (such as installing iIS process management tools), as well.

This section describes what the installation program does on each of the following four node types:

• central server

• engine server

• client development (process development or client application development)

• runtime client

For platform-specific information and installation program details, see the iIS Installation Guide.

56 iPlanet Integration Server • Process System Guide • August 2001

Setting Up an iIS Process System

Central Server Installation

On a central server node—the first node to be installed in an iIS system—the iIS installation program performs the operations described in the following table:

Operation Software Module FORTE_ROOT

directory

Prepares node as the central distribution node for all distributions.

All application distributions

appdist

All library distributions

Loads distributions into environment repository to enable deployment by iPlanet UDS system management agents.

Transfers iIS repository files to node. WFSeed.btx

All server application distributions All library distributions

WFSeed.btd

——

install/respos cpy

Creates iIS repository server. repos

Installs engine components. WFEngineUnit

userapp WFGovernor WFDatabaseSvc

Installs process development libraries. WFLibrary

userapp WFModel WFAccessServiceObj

Installs iIS TOOL client development libraries.

WFClientLibrary WFProcMgrLibrary

userapp

WFAdminLibrary

Installs iIS C++ client development DLL. WFClientAPI userapp

Installs CORBA/IIOP interface service. WFCORBAapi userapp

Installs iIS process management client applications.

Installs iIS system libraries. OFCustomIF

Installs registration support service. WFEnvAgent userapp

Installs message catalog file en_us.cat install/nls/co

Installs Dump/Restore facilities WFDrWind

WFConsole

userapp WFScript

userapp WFCustomIF WFEnvDefinition

nductr

userapp WFDrDump WFDrRest

Chapter 2 Setting Up an iIS Process Management System 57

Setting Up an iIS Process System

Engine Server Installation

On an engine server node, which must be installed after the central server node, the iIS installation program performs the operations described in the following table:

Operation Software Module FORTE_ROOT

directory

Transfers iIS repository files to node. WFSeed.btx

install/resposcpy

WFSeed.btd

Installs engine components. WFEngineUnit

userapp WFGovernor WFDatabaseSvc

Installs process development libraries. WFLibrary

userapp WFModel WFAccessServiceObj

Installs iIS TOOL client development libraries.

WFClientLibrary WFProcMgrLibrary

userapp

WFAdminLibrary

Installs iIS C++ client development

WFClientAPI userapp

DLL.

Installs iIS system management client applications.

Installs iIS system libraries. OFCustomIF

WFConsole WFScript

userapp

userapp WFCustomIF WFEnvDefinition

Installs message catalog file en_us.cat install/nls/conductr

Installs Dump/Restore facilities WFDrWind

58 iPlanet Integration Server • Process System Guide • August 2001

userapp WFDrDump WFDrRest

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

install/resposcpy

WFSeed.btd

Installs process development libraries. WFLibrary

userapp WFModel WFAccessServiceObj

Installs iIS TOOL client development libraries.

WFClientLibrary WFProcMgrLibrary

userapp

WFAdminLibrary

Installs iIS C++ client development DLL. WFClientAPI userapp

Installs iIS process management client applications.

Installs iIS system libraries. OFCustomIF

WFConsole WFScript

userapp

userapp WFCustomIF WFEnvDefinition

Installs message catalog file en_us.cat install/nls/conductr

Chapter 2 Setting Up an iIS Process Management System 59

Setting Up an iIS Process System

Runtime Client Installation

On a runtime client node, which must be installed after the central server node, the iIS installation program performs the operations described in the following table:

Operation Software Module FORTE_ROOT

directory

Installs iIS TOOL client libraries. WFClientLibrary

WFProcMgrLibrary WFAdminLibrary

Installs iIS C++ client development DLL. WFClientAPI userapp

Installs iIS process management client applications.

Installs iIS system libraries. OFCustomIF

Installs message catalog file en_us.cat install/nls/conductr

WFConsole WFScript

WFCustomIF WFEnvDefinition

userapp

Configuring and Starting Your iIS Engines

When your iIS process system software is installed on the various nodes in your environment (including an iIS central development repository), an iIS application system designer can begin implementing the various design elements, process developers can begin creating process definitions, and client application developers can begin writing iIS client applications.

However, before long it will be necessary to have a test engine running in your environment. Configuring and starting an iIS process engine requires familiarity with iIS process management tools (see Chapter 3, “The iIS Console”) and is described fully in Chapter 4, “Managing Engines.”

60 iPlanet Integration Server • Process System Guide • August 2001

Maintaining an iIS Process System

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. For example, you need to regularly back up the central development repository as well as compact it from time to time (see the iPlanet UDS System Management Guide for more information). Also the engine database must be monitored to make sure you do not run out of disk space.

Other maintenance tasks might include the following:

• adding new nodes to an iIS system

• moving an iIS process engine

• creating a new iIS Repository Server

• moving an iIS Repository Server

Maintaining an iIS Process System

• creating a private iIS repository

• uninstalling an iIS system

Each of these are discussed briefly below.

Adding New Nodes to an iIS System

➤ To add a new node to an iIS system

1. Decide which function the new node is to perform in your iIS system.

2. Run the iIS installation program and choose the appropriate installation

option.

Chapter 2 Setting Up an iIS Process Management System 61

Maintaining an iIS Process System

3. Choose default or custom installation, depending on the components you want

to install on the node.

NOTE If you know the application or library distributions required for the

Moving an iIS Engine

Moving an iIS engine or engine component is straightforward. You move the engine or engine component to a different engine server node by reconfiguring the engine as described in “Configuring an Engine” on page 85. If the target node is not presently an engine server node, install iIS system software on the target node using the instructions in “Adding New Nodes to an iIS System” on page 61.

new node (see Table 2-1 on page 47), you can install them using iPlanet UDS system management services rather than the iIS installation program. The distributions can be installed on the new node using Escript or the iPlanet UDS Environment Console, depending on whether the new node is a client or server, as described in the iPlanet UDS System Management Guide.

Creating a New iIS Repository Server

➤ To create a new iIS Repository Server

1. Decide which node is to host the new repository server.

2. Run the iIS installation program and choose the Engine Server option.

3. Choose Custom Installation.

4. Check Create iIS Repository and clear all other options.

5. Click OK and follow the screen questions and instructions.

Moving an iIS Repository Server

➤ To move an iIS Repository Server

1. Select a server node to host the relocated repository server.

2. Shut down the current Repository Server.

62 iPlanet Integration Server • Process System Guide • August 2001

Maintaining an iIS Process System

3. 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. Copy the two repository seed files (wfseed.btx and wfseed.btd) from

FORTE_ROOT/resposcpy to FORTE_ROOT/repos.

2. Rename the two files to correspond to the name of your iIS private repository.

You might have to modify the files to provide read/write access.

3. Edit the iPlanet UDS Distributed or iPlanet UDS Standalone system icons that

start iIS.

Set the -fr flag in the icon’s command line to reference the new private repository. For more information, refer to instructions about starting the process development environment in the iIS Process Development Guide.

Upgrading an iIS System

Upgrading an iIS system is generally straightforward: You install the new version of iIS system software over the older version. Engine configuration files can be used with the new version, though you might want to reconfigure engines to make use of new engine configuration options.

The situation in which you must exercise caution, however, is if you have state or history information in your engine database that you need to preserve across the upgrade. If the engine database schema changes from the older version to the newer version of iIS, you must migrate that data from the older database schema to the new one. iIS provides Dump/Restore facilities to use for this purpose. See

“Dumping and Restoring Data” on page 126, and be sure to check all release notes.

Chapter 2 Setting Up an iIS Process Management System 63

Maintaining an iIS Process System

Uninstalling an iIS System

Because iIS server software is installed using iPlanet UDS system management services, the iPlanet UDS environment repository has a record of all engine components installed on servers in your environment. To uninstall an iIS system, first use iPlanet UDS system management tools (Environment Console or Escript) to uninstall these components from the environment.

In addition, uninstalling an iIS system requires removing the various iIS system software components from the various nodes on which they have been installed. The components—application partitions and libraries—are installed in a standard iPlanet UDS location on each node: FORTE_ROOT/userapp/distribution_ID, where distribution_ID is the name of the software module. (For the names of the software modules installed on each type of node, see “The iIS Installation

Program” on page 56.)

To revert a repository to a non-iIS development repository, you need to delete all the libraries imported by the iIS installer. After deleting the WFLibrary distribution from FORTE_ROOT/userapp, the iIS-specific buttons and menus are removed from the Repository Workshop, and no longer appear on startup.

64 iPlanet Integration Server • Process System Guide • August 2001

Chapter 3

The iIS Console

This chapter describes the iIS Console, the iIS product’s window-based tool for performing iIS process management tasks.

This chapter assumes that you have set up an iIS process management system and have installed iIS process management applications (iIS Console and Conductor Script) on at least one node in your environment.

This chapter covers the following topics:

• overview of the iIS Console

• starting the iIS Console

• using the iIS Console window

• navigating to other iIS Console windows

• summary of menu commands

Overview

The iIS Console is the main system management application for performing iIS process management tasks. The iIS Console has a graphical user interface, as opposed to Conductor Script, which has a command line interface.

NOTE Neither the iIS Console or Conductor Script can be used to perform

backbone system management tasks. For information on backbone system management, refer to the iIS Backbone System Guide.

Overview

The iIS Console is used for the following four general kinds of iIS process management tasks:

• configure and manage process engines

The iIS Console provides a set of windows that let you configure a new iIS engine, start and view the status of an already configured engine, and reconfigure an existing engine, if necessary.

• manage registration

You can register a number of process logic components created in the iIS process development workshops with one or more iIS engines. When these software components are registered, they can be dynamically loaded by an engine and used in process execution.

• manage process execution

Using the iIS Console, you can monitor the activity of an engine and make administrative adjustments when necessary. You can monitor engine sessions and send messages to client applications, and you can monitor the engine’s execution of individual processes.

• monitor alarms and diagnostic messages

You can monitor high priority events (alarms) from within the iIS Console, as well as view diagnostic messages generated by engine components. All these alarms and messages are useful in troubleshooting problems in engine performance and process execution.

The iIS Console connects to and communicates with the executing iPlanet UDS Environment Manager and any active Node Managers in your iPlanet UDS environment. It gives you access to iIS engine agents: objects that control engine components and provide information about process execution.

NOTE The Conductor Script command line utility is functionally

equivalent to the iIS Console. However, all procedural instructions in this guide assume you are using the iIS Console. For information on Conductor Script, see Appendix A, “Conductor Script

Commands.”

66 iPlanet Integration Server • Process System Guide • August 2001

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. Enter a valid password if one is requested (see “Setting Password Protection

for iIS Console” on page 71).

When the iIS Console starts, it opens the iIS Console main window shown in

Figure 3-1 on page 69.

Starting the iIS Console

Using the cconsole Command

As mentioned above, you start the iIS Console on command-line-based operating systems by executing the

The syntax of the

cconsole [-fl log_flags][-fm memory_flags]

The syntax of the cconsole command for OpenVMS:

VFORTE CCONSOLE

[/LOGGER=log_flags] [/MEMORY=memory_flags]

As in all iPlanet UDS command line specifications, if you use a name that includes a space, you should enclose the name in double quotation marks.

cconsole command for most platforms:

cconsole command.

Chapter 3 The iIS Console 67

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

-fm memory_flags /MEMORY=

memory_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.

Specifies the memory flags to use for the iIS Console session. See the iPlanet UDS System Management Guide for syntax information. Overrides defaults appropriate for the operating system. On UNIX, you must specify the memory flags in double quotes.

The iIS Console Main Window

The iIS Console main window is a view of configured iIS process engines in your active environment. In the main window, you can initiate all system management tasks you want to perform in your iIS process system. You can use the main window to manage engines, registrations, and process execution in your environment. You can also add password protected access to iIS Console.

The iIS Console main window consists of two areas: the main viewing panel and the menu bar.

68 iPlanet Integration Server • Process System Guide • August 2001

Active environment

Engines

Main viewing panel

The iIS Console Main Window

Figure 3-1 iIS Console Main Window

Menu bar

Popup menu

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.

Error state Engine has encountered an exception while attempting to start.

Most tasks you perform using the iIS Console are initiated by first selecting an engine from the main viewing panel and then selecting the desired operation from the appropriate menu.

Chapter 3 The iIS Console 69

The iIS Console Main Window

Menu Bar

The iIS Console menu bar provides all the commands you can execute from the main window. The menus are summarized below, and a full list of the commands is provided at the end of this chapter.

The main window menus are:

Environment menu Provides environment-wide iIS Console commands (such as for registrations), or general commands such as opening a window to see alerts being generated from iIS process engines.

View menu Provides commands for setting refresh properties of the window.

Engine menu Provides engine management commands for configuring, starting

up, viewing the status of, deleting, performing logging and trace functions, and shutting down an iIS engine.

Monitor menu Provides commands for monitoring and managing processes being executed by an iIS engine, verifying registrations, and charting performance.

Help menu Provides online Help for the iIS Console.

Mouse Popup Menu

iIS Console windows support a popup menu activated by the right mouse button. The popup menu depends upon the item selected in the window. In the case of the main window, the popup menu includes the following subset of commands from the menu bar:

Engine menu Reconfigure, Delete, Start, Logging, Trace, Event Trace, Status, Shut Down

Monitor menu Sessions, Processes Summary, Processes Resident, Activity Queues, Activities Resident, Registrations, Performance

Online Help

Online Help is available from iIS Console.

• To display the Help Topics window, choose Help > Help Topics.

• To display help for the current window, press the F1 or Help key (depending

on your operating system platform).

70 iPlanet Integration Server • Process System Guide • August 2001

The iIS Console Main Window

Setting Password Protection for iIS Console

You can restrict access to iIS Console by setting password protection for your active iIS environment. A password is then required to open iIS Console, as well as any other system management tools, such as Conductor Script and the iPlanet UDS Environment Console.

Once you set a password, other users cannot open iIS Console (or Conductor Script or the iPlanet UDS Environment Console) in your active environment without using the password.

➤ To set a password for iIS Console

1. Choose Environment > Set Password. The Enter Password window displays.

2. Enter a password and then enter it again in the Verification password field.

3. Click OK to set the password.

You can also use this window to change password protection for an environment by first entering the current password in the Password field and then entering the new password. If you want to remove password protection, enter the current password in the Password field, then enter nothing for the New password and click OK.

Exiting iIS Console

To exit the iIS Console, choose Environment > Exit.

Chapter 3 The iIS Console 71

Using iIS Console Windows

The iIS Console is a graphical system application developed in iPlanet UDS whose windows behave in accordance with your host window system. If you use graphical applications in your host window system, the Console will be familiar.

Using the Mouse

The iIS Console behaves like any standard application in your window system—mouse clicks select objects, double-clicks open objects, and click-and-drag operations move or copy objects. If your mouse has more than one button, you use the left-most button for these operations (or, if your mouse is configured specifically for left-handed use, the right-most button).

The iIS Console also uses the right-most button to present popup menu commands as an alternative to using the menu bar. The popup menu choices presented by right-clicking depend on which, if any, items are selected in the active window.

Window Refresh Behavior

Many iIS Console windows display lists that are maintained by the engine and are in a constant state of change. iIS Console lets you determine if and how often window displays are refreshed to correspond to information maintained by the engine. Each display window has a default automatic refresh time interval setting.

You can turn automatic refresh off or on, set the automatic refresh interval, or force an immediate refresh.

➤ To turn automatic refresh off or on

1. Enable the Automatic Refresh toggle in the bottom right of the window.

72 iPlanet Integration Server • Process System Guide • August 2001

Using iIS Console Windows

➤ To set the automatic refresh interval

1. Choose View > Set Refresh Interval. The Refresh Interval window displays

with the default time interval setting:

2. 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.

Filtering iIS Console Lists

Many iIS Console windows provide lists you can filter using commands available on the View menu and in the right mouse button popup menu. This section describes techniques used to perform these filtering operations.

For example, suppose you select an engine and then choose Monitor > Sessions to display a list of sessions for that engine. You can filter the list displayed or find sessions that meet certain criteria using the Filter and Find commands.

Selecting Filter from the View menu or the mouse menu displays a window in which you can write an expression for filtering the session list. The expression must be of the form:

Column_name <operator> value

Chapter 3 The iIS Console 73

Using iIS Console Windows

Operators

You can build filter expressions that use both comparison and logical operators. The comparison operators are listed in the following table:

Comparison Operator Description

=equal to

<> not equal to

< less than

> greater than

<= less than or equal to

>= greater than or equal to

You can use a number of logical operators to join several filter expressions. The logical operators are listed in the following table:

Logical Operator Description

and logical and

or logical or

not logical not

Specifying Values

In a filter expression you specify the value of an object’s state or status. These are expressed as case-sensitive string values and should be enclosed in double quotes:

Object State/Status Value

Session Active

Session Suspended

Activity PENDING

74 iPlanet Integration Server • Process System Guide • August 2001

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.

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. In the Processes Resident window that opens, choose View > Sort.

3. Select the item to sort by, and indicate ascending or descending order.

76 iPlanet Integration Server • Process System Guide • August 2001

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.

Using List Views

The iIS Console provides iPlanet UDS list views in the main window and the Engine Status window so you can browse engines and engine components.

You might be familiar with list views as the file directory display mechanism in your host window system. iPlanet UDS list views behave like the File Manager application in Microsoft Windows. This program displays hierarchical information successively indented from left to right. To select an element in a list view, you click it. To open an element to get a list of sub-elements, you double-click the element, then either press Enter while it is selected or click its expansion box.

Expansion box

The expansion box lets you open or close the list of elements “below” the current element in the hierarchy. If the expansion box displays a + (plus), click the box to open the list. If the expansion arrow displays a – (minus), click the box to close the list.

Figure 3-2 iIS Console Browser

Chapter 3 The iIS Console 77

iIS Console Main Window Command Summary

The following tables summarize the commands available from the iIS Console main window.

Environment Menu

Command Description See…

Alarms… Lets you view all alarms received from the

selected engine.

Registrations… Provides submenus for registering (and

unregistering) process definitions, assignment rules, user validations, and user profiles with one or more engines.

Aliases… Provides submenus for registering (and

unregistering) aliases with one or more engines. Aliases are used in specifying subprocess activities.

Set Password… Opens a password entry window where you

can set password protection for opening iIS Console in your active environment. Once you set a password, other users cannot open the iIS Console (or Conductor Script) in that environment without using the password.

Print… Prints the iIS Console main window. —

Print Setup… Displays the Page Setup window for the

window system.

Exit Closes the iIS Console and all open windows. page 71

page 208

page 144

page 148

page 71

—

78 iPlanet Integration Server • Process System Guide • August 2001

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.

Set Refresh Interval… Opens a Refresh Interval window where you

can set the time interval between automatic refreshes of the window display.

Window List… Displays a list of open windows from which

you can select a window to bring to the foreground.

page 72

—

Engine Menu

Command Description See…

New… Opens a new engine configuration window in which you

specify the component partitioning and static properties of a new engine.

Reconfigure… Opens an engine configuration window for the selected

engine in which you can modify the component partitioning and startup properties as specified in the engine configuration file.

page 85

page 113

Duplicate… Creates a duplicate of the selected engine. A duplicated

Delete Lets you delete an engine configuration for the selected

Start… Opens an engine startup window in which you can start

Logging… Opens a dynamic database reconfiguration window in

page 104

engine contains the same configuration as the original engine.

page 104

engine.

page 105

the selected engine or any of its components.

page 115

which you can dynamically change which database tables are being logged (current state or history log or both) as well as change the history log volume. The changes you make in this window do no change the startup configuration.

Chapter 3 The iIS Console 79

iIS Console Main Window Command Summary

Command Description See…

Trace… Opens an engine trace window in which you display

page 212

messages, of the type you specify, generated by the various engine components.

Event Trace… Opens the engine event filter window which lets you

page 217

select the type of filter to use for displaying engine events as well as a filter time interval.

Status… Opens an engine status window in which you can view

page 117

the status of the selected engine or any of its components. You can also change the state of engine units.

Shut Down Shuts down the selected engine and all its components. page 124

Monitor Menu

Command Description See…

Sessions… Opens the engine sessions window, which displays the

list of active sessions for the selected engine. You can monitor and manage sessions from this window.

Processes Summary…

Opens the processes summary window, which displays the list of all process definitions for the selected engine and the number of instances of each. You can open a named process definition to get a list of the process instances, displaying information about each.

page 173

page 221

Processes Resident…

Activity Queues…

80 iPlanet Integration Server • Process System Guide • August 2001

Opens the engine process instances window, which displays the list of all process instances for the selected engine. You can sort this list by process name, primary process attribute, process_id, or creation time. You can open a listed process instance to get information about its activities, attributes, timers, and so on.

Opens the engine activity queues window, which displays the list of all activity queues for the selected engine. Activity queues are always resident in the engine. You can open a listed queue to get a list of activities in the queue, and so on.

page 179

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.

Registrations… Opens the engine registrations window, which displays

the list of process definitions, assignment rules, user profiles, user validation, and aliases currently registered with the selected engine. This window can be the launch point for monitoring and managing execution of processes registered with the engine—for example, you can monitor the status of all process instances of a given named process. You can also deregister a registered item from the selected engine.

Performance… Opens the performance window, which displays

histograms of four agent data types (instruments) that characterize the performance of the selected engine.

page 179

page 150

page 221

Help Menu

Command Description See…

Contents Opens the Help Topics window that lets you navigate

the iIS process management online help system.

About iIS… Displays information about the iIS product. —

page 70

Chapter 3 The iIS Console 81

iIS Console Main Window Command Summary

82 iPlanet Integration Server • Process System Guide • August 2001

Chapter 4

Managing Engines

This chapter describes how to manage iIS process engines. It covers the following topics:

• configuring an engine

• starting an engine

• monitoring and changing the state of an engine

• reconfiguring an engine to accommodate increased load, improve

performance, or recover from failure

• managing an engine database

Production Engines Versus Development Engines

Engine use in production environments can differ significantly for use in development environments. In a development environment, the engine is used principally for testing and debugging purposes, while in a production environment, the engine must support mission-critical operations.

These different use requirements translate into differences in the way you are likely to configure and manage an engine. The table below summarizes some of the issues.

Production Engine Development Engine

Multiple engines might be needed for organizational reasons or to handle heavy production loads.

A single engine is normally sufficient for testing purposes.

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.

Backup engine unit and governor is needed for failover.

A number of database services are normally required to meet engine performance (database access) requirements.

Historical process execution information is needed to analyze and improve system performance: logging of historical state information is normally turned on.

Engine is rarely cold started: registration and history information would be lost.

Application upgrades need to be performed without interrupting process execution.

Resource limitations need to be monitored to ensure engine performance and stability: memory, disk space, and cpu utilization.

State information does not need to be stored in the engine database: current state logging can be turned off.

Failover is not critical: a minimal engine configuration is adequate.

A single database service is normally adequate.

Current process execution information is more important than historical information: history logging can be turned off.

Engine is often cold started: registration information is purged, allowing for a clean engine state.

Engine can be shut down and cold started to perform application upgrades.

Resource limitations rarely are of concern in development environments.

Keep these issues in mind when configuring an engine. In most situations, you have to configure and manage at least one development engine and one production engine.

NOTE Do not use the same engine for both development and production.

84 iPlanet Integration Server • Process System Guide • August 2001

Configuring an Engine

An iIS process system can have any number of engines. For example, one engine might be used for testing and another used for production. In other cases, organizational considerations or heavy load conditions might require a number of production engines. While engines can communicate with one another—a process executing on one engine can be invoked from a process executing on another—each engine operates independently. One engine, for example, cannot fail over to another engine.

Each engine is composed of a number of engine components—engine units, governor, and database services (see Chapter 1, “Introduction: iIS Process

Management”). For each engine to function independently, its components must

each be identified with the engine and have a unique name, provided at startup time.

Each engine requires two levels of configuration:

• engine component partitioning

Configuring an Engine

Specify which computer nodes in your environment will host the different engine components—engine units, governor, and database services.

• engine startup properties

Specify a number of startup properties required by the various engine components.

The two levels of configuration are considered separately, below.

Engine Component Partitioning

An engine that is fully configured for failover and load balancing includes all the engine components shown in Figure 4-1, described on page 35.

Chapter 4 Managing Engines 85

Configuring an Engine

Figure 4-1 Engine Configuration with both Failover and Load Balancing

iIS Process

Client Applications

Engine

Governor

Primary

Engine

Unit

Router

Database

Services

Database

Services

Backup

Engine

Unit

Engine

Database

During installation, you decided which nodes in your iPlanet UDS environment (engine servers) would have engine components installed on them. You must also determine your engine component partitioning: which engine components (if any) will run on each engine server.

The partitioning scheme that provides the highest failover reliability and the highest performance depends on a number of different factors. These factors include the power and reliability of your servers, the bandwidth of your network, the normal load on the iIS process engine, and how this load is distributed over a typical work day. Since these factors vary from site to site, only some very general guidelines are discussed here.

Primary Engine Unit It is recommended that you assign the primary engine unit to a fast, reliable server node. The primary engine unit in a production situation normally maintains sessions with hundreds of clients, maintains state information on tens of thousands to millions of objects, and performs all the computations required of an engine.

Backup Engine Unit It is recommended that you assign the backup engine unit to a capable server node also, but a different one from the node on which the primary engine unit runs (to provide backup should the primary server fail). This node could be a less powerful computer if you are willing to accept a possible decrease in performance for your backup unit.

86 iPlanet Integration Server • Process System Guide • August 2001

Configuring an Engine

Governor The governor does not do much processing and does not require a high performance server. It is recommended that you not assign it to the same server as either the primary or backup engine unit, because it would then not be able to distinguish between failure of the primary engine unit and a break in the network link between the engine units.

Database Services The number and placement of database services depends on load conditions. You must have enough database services running to prevent database access requests from backing up in the database service router (see

“Viewing Performance Indicators” on page 222). In general, assign high priority

database services to a very capable server node, probably the same as the one on which the database manager resides. If your database system provides network access to the database, such as ORACLE’s SQL*Net, then lower priority database services can be assigned to under-utilized servers, where resources are available to help carry heavy loads on the engine. (If your database system does not provide network access to the database, then your database services must reside on the same node as your database manager.)

A typical configuration is illustrated in Figure 4-2 on page 88.

In this illustration the database services on Server4 are used in a round-robin fashion unless the load on the engine is too heavy for them to carry it. In that case the database service on Server1 is used. The database service on Server3 will be used to handle peak loads, but will get less work than the service on Server1.

You did not have to decide at iIS installation time exactly which engine components would be assigned to each server node because all component partitions are installed on each server node that supports an engine. Instead, you must select which components to start on which nodes when you configure each engine.

For example, you can designate a default set of database services that are started at engine startup time. Subsequently, however, you can start up additional database services on designated nodes, as needed, to accommodate increasing load on the engine.

The location of the primary and backup engine units is best determined in advance, before startup time, and should not change because the shared library files corresponding to process definitions registered with the engine are needed on all the nodes on which the engine units are located. For this reason, moving the engine units from one node to another can take a long time.

Your default engine component partitioning scheme is stored in an engine configuration file, allowing you to design your basic engine component partitioning scheme in advance and consistently start up your engine the same way every time.

Chapter 4 Managing Engines 87

Configuring an Engine

Figure 4-2 Typical Engine Partitioning Scheme

Clients

Server 1

Governor

Database

Service

Server 2

Primary Engine Unit

Router

Server 3

Backup Engine

Unit

Database

Service

Priority=9

Priority=8

Engine Startup Properties

Before you start an engine, you must specify a number of startup properties. These properties are stored in the engine configuration file. The startup properties are the following:

88 iPlanet Integration Server • Process System Guide • August 2001

Server 4

Database

Services

Engine

Database

Priority=10

Configuring an Engine

Engine name An alpha-numeric name used to identify the engine in a given environment.

Environment An alpha-numeric name that specifies the iPlanet UDS environment in which the engine resides.

Database Configuration Properties Properties needed to access the engine database. These properties include:

• database type

• database name

• user name

• user password

Database Logging Settings These settings specify whether state information is logged and which history information tables are updated by the engine.

Process Engine Components A minimal engine configuration contains an engine unit component and a database service component. An engine configured for failover also contains a Governor component.

Memory Settings These settings specify the object memory heap size allocated to the various engine components (governor, database services, and engine units). Included here is also a setting to limit the number of console monitor windows that can be open at any time.

Stack Size These settings specify the memory size of each thread started for the process engine components. Default values vary for each platform. Typically, you do not need to override the default values. For information on setting stack size in an iPlanet UDS environment, refer to the discussion on FORTE_STACK_SIZE in the iPlanet UDS System Management Guide.

Process Execution Options These settings specify how an engine manages process execution. By setting these options appropriately, you can ensure that memory resources do not become overtaxed during process execution, and thereby avoid engine performance degradation or possible failure.

Engine Recovery Options These options specify the behavior of the engine during recovery from an engine failure. They determine how long an engine waits for client sessions to reconnect, and the action to take if the client sessions do not reconnect after the timeout period expires.

Chapter 4 Managing Engines 89

Configuring an Engine

Engine Configuration File

The engine component partitioning and engine startup properties are stored in an engine configuration file in the following location on the central server node in your environment:

FORTE_ROOT/sysdata/conductr/clN/environment/engine_name.cfg

Path Element 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.0 GOVERNOR = Server4 UNITS = Server1:Primero:P,Server3:Secundo:B DBSERVICES = Server2:DBService1:10,Server4:DBService2:9,… DATABASE_TYPE = ORACLE DATABASE_NAME = @oracle_Server2 DATABASE_USER_NAME = wftester DATABASE_USER_PASSWORD = *#@$!! LOGGING= ON,STATE,LOG,LOG_ACTIVITIES,LOG_ATTRIBUTES,LOG_LOCKS,… GOVERNOR_MEMORY_FLAG = n:2000,x:10000,… DBSERVICE_MEMORY_FLAG = n:2000,x:10000,… UNIT_MEMORY_FLAG = n:10000,m:30000,… GOVERNOR_STACK_SIZE = 48000 DBSERVICE_STACK_SIZE = 96000 UNIT_STACK_SIZE = 96000 UNIT_RECOVER_CURSOR_SIZE = 123 DATABASE_PROC_SEGMENT_SIZE = 256 DATABASE_SESS_SEGMENT_SIZE = 256 UNIT_MAX-SESSION_NUMBER = 300 UNIT_MAX-PROCESS_NUMBER = 0 UNIT_IN_MEMORY_PROCESS_LIMIT = 1000 UNIT_SWAPOUT_INTERVAL = 10000 MONITOR_DISPLAY_LIMIT = 10 UNIT_SESSION_RECONNECT_LIMIT = 600000 UNIT_SESSION_RECONNECT_ACTION = 2048 UNIT_SNS_RATIO = 70

90 iPlanet Integration Server • Process System Guide • August 2001

Configuring an Engine

The engine properties specified in the configuration file are described in the following table:

Table 4-1 Process Engine Configuration Properties

Property Type of

value

FILE_VERSION string Internal use. Do not modify.

GOVERNOR string Specifies the node on which governor

UNITS string For each engine unit, specifies the node on

DBSERVICES string For each database service, specifies the node on

Description

component runs.

which the unit runs, unit name, and preferred priority (P=primary unit, B=backup unit, or N=no preference). String contains entries, separated by commas, in the form [NODE_NAME:UNIT_NAME:P/B/N][,…].

which the service runs, service name, and priority (integer—positive or negative). String contains entries, separated by commas, in the form [NODE_NAME:SERVICE_NAME:PRIORITY][, …].

DATABASE_TYPE string Database type. Can have the following values:

ORACLE, SYBASE, …(any database system supported by iPlanet UDS).

DATABASE_NAME string Name of database.

DATABASE_USER_NAME string Database logon user name.

DATABASE_USER_PASSWORD string Database logon password. The password is

encrypted.

LOGGING string Specifies which tables (current state and history

log) are enabled and which object state changes are recorded if the history log is enabled. String contains any of the following entries, separated by commas, that are enabled: [STATE] [,LOG] [,LOG_ACTIVITIES] [,LOG_ATTRIBUTES] [,LOG_LOCKS] [,LOG_PROCESSES] [,LOG_SESSIONS] [,LOG_TIMERS]

Chapter 4 Managing Engines 91

Configuring an Engine

Table 4-1 Process Engine Configuration Properties (Continued)

Property Type of

value

Description

GOVERNOR_MEMORY_FLAG string 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. Uses the same

syntax as the -fm flag used on iPlanet UDS partitions. Default values are n:2048,x:16384,….

GOVERNOR_STACK_SIZE DBSERVICE_STACK_SIZE UNIT_STACK_SIZE

integer Specifies the memory size for each thread

started for the process engine components. Default values vary for each platform.

For information on setting stack size in an iPlanet UDS environment, refer to the discussion on FORTE_STACK_SIZE in t

iPlanet UDS System Management Guide

UNIT_RECOVER_CURSOR_SIZE string Specifies number of process instances to be

recovered at one time in the event of engine unit failure.

DATABASE_PROC_SEGMENT_SIZE integer Specifies segment size for storing text-based

process attributes. Default value is 255 bytes.

DATABASE_SESS_SEGMENT_SIZE integer Specifies segment size for storing text-based

session attributes (associated with a session’s user profile). Default value is 255 bytes.

UNIT_MAX_SESSION_NUMBER integer Specifies number of concurrent sessions

supported by the engine. Default value is 300.

UNIT_MAX_PROCESS_NUMBER integer Specifies the number of concurrent process

instances supported by the engine. Default value is 0 (no maximum).

UNIT_IN_MEMORY_PROCESS_LIMIT integer Specifies the number of process instances

retained in memory. Default value is 1000.

UNIT_SWAPOUT_INTERVAL integer Specifies the time interval (in milliseconds) at

92 iPlanet Integration Server • Process System Guide • August 2001

which the engine checks the number of process instances resident in memory and swaps out dormant process instances. Default value is

10000.

Configuring an Engine

Table 4-1 Process Engine Configuration Properties (Continued)

Property Type of

value

MONITOR_DISPLAY_LIMIT integer Specifies the maximum number of Cconsole

UNIT_SESSION_RECONNECT_LIMIT integer During engine recovery, specifies the time (in

UNIT_SESSION_RECONNECT_ACTION integer During engine recovery, specifies the action to

Description

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.

milliseconds) that an engine waits for clients to reconnect to a session. Default value is 60000 milliseconds (10 minutes).

take (suspend or terminate) for client sessions that fail to reconnect before the specified timeout period (UNIT_SESSION_RECONNECT_LIMIT). Default value specifies to suspend sessions that do not reconnect.

UNIT_SNS_RATIO integer Specifies the ratio of swapable to non-swapable

processes for the process engine. Processes that are not marked as recoverable (either through the process definition or by a process client calling CreateProcess) cannot be swapped out of memory by the engine. Adjust the default value only if you are having performance problems with the process engine.

Customizing Engine Database Schema

iIS provides a default database schema that it uses to create an engine database. This default schema can be used in a development environment without modification. However, for deployed applications, you can modify the database schema according to your own database requirements. Typically, you modify the schema to add table space qualifiers or other database-specific qualifiers to the CreateTable and CreateIndex statements.

Chapter 4 Managing Engines 93

Configuring an Engine

When you configure a new engine, the default engine schema is specified by the following file on the central server node in your environment:

FORTE_ROOT/sysdata/conductr/clN/environment/engine_name.dbs

Path Element 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. When you perform a cold start on an engine, iIS uses the specification in this file to create the engine database.

If you want to modify the default schema, before performing a cold start on an engine, edit this file according to your needs.

CAUTION When modifying an engine database schema, do not change any

basic table definitions or index definitions, and do not change any column names or column data types. You should only modify information specific to a database or site, such as the table space qualifiers. Otherwise, the engine may not start. Examine the engine log file (at FORTE_ROOT/log) to determine the cause of startup failure.

94 iPlanet Integration Server • Process System Guide • August 2001

Configuring an Engine

The following example shows how to modify the create index statement for the WFHActivity table to include a table space qualifier.

Code Example 4-1 Generated Definition (Oracle)

create unique index wfk_act on WFHActivity (

processid, id)

</FNCreateIndexStatement>

Code Example 4-2 Modified Definition

create unique index wfk_act on WFHActivity (

processid, id) TABLESPACE my_ProcessEngine_Index

</FNCreateIndexStatement>

How to Configure a New Engine

The easiest way to configure a new engine is to use the iIS Console to create a new engine configuration file and place it in the proper directory location on your central server node. (You can also create a new configuration file by directly entering the information in “Engine Configuration File” on page 90 into the file.)

Chapter 4 Managing Engines 95

Configuring an Engine

➤ To configure a new engine

1. Choose Engine > New. The Configure New Engine window displays:

2. 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. Click the Database tab to display the database properties dialog:

96 iPlanet Integration Server • Process System Guide • August 2001

Configuring an Engine

4. Enter the database configuration properties.

For information on the Database Connection fields, refer to the iIS online help. The Text Attribute Segment Size fields allows you to specify the segment length for process attributes and user profile information for a session.

Property Description

Process attribute segment size

User profile attribute segment size

Specifies segment size for storing text-based process attributes. Default value is 255 bytes.

Specifies segment size for storing text-based session attributes (associated with a session’s user profile). Default value is 255 bytes.

5. Click the Logging tab to display the logging properties dialog:

Chapter 4 Managing Engines 97

Configuring an Engine

6. Specify the engine database tables (Current state and/or History log) for which

you want to log information. If you write to history log tables, specify the information to log.

Current state This setting determines whether the engine writes information about the current state of all sessions, processes, and process components to the current state tables (see Appendix B, “Engine Database Schema”). You cannot recover an engine or support failover of an engine unit unless you enable the Current state option.

History log This setting determines which information, if any, the engine logs about each state change in sessions, processes, and process components to the history log tables (see Appendix B, “Engine Database Schema”). The history log tables are used for obtaining historical information about process execution. The history log can grow quite large, so set logging selectively. You may have to monitor, back up, and flush the history log tables on a regular basis. For more information, see “Managing an Engine Database” on page 124.

NOTE The registration tables are always enabled for registering

process definitions, assignment rule dictionaries, user profiles, a validation, and aliases. Therefore, no option for the registration table appears in the dialog.

98 iPlanet Integration Server • Process System Guide • August 2001

7. Select the Components tab.

The Component Partitioning dialog is displayed.

Configuring an Engine

8. Specify the engine component partitioning.

When assigning a component to a node, be sure that the node is an engine server node (that is, that engine components were installed on the node during iIS installation). The Node drop list shows all server nodes (whether online or not) defined in the iPlanet UDS environment.

The order in which you specify components is not important.

Governor To provide failover for an engine, you need to include a governor in the configuration. The governor does not accept a name or priority (indicated by “N/A” in the table).

Engine Unit You can specify one or two engine units in your configuration—to provide failover, you need two units (a primary and a backup). For each engine unit, you must provide a name and indicate whether it is the primary unit (P), backup unit (B), or not specified (N). In the last case the governor decides which is primary and which is backup. For failover to work, the engine units must be put on separate nodes and cannot be on the node hosting the governor.

Database Service You can specify as many database services as you need (at least one) to balance the maximum load on your engine database access. For each database service, you must provide a unique name and indicate its priority. A priority is simply an integer (positive or negative from 1 to 10), with

Chapter 4 Managing Engines 99

Configuring an Engine

a higher numeric value signifying a higher priority. It is suggested that you decide on a sensible set of priorities. A default priority of “1” is used if you do not specify a priority. The engine distributes the database access load based on this priority. See “Full Configuration: Failover and Load Balancing Combined”

on page 35.

Database services must be placed on the node where your database manager resides, unless your database system provides network access to the database, such as ORACLE’s SQL*Net. If your database system provides network access to the database, then lower priority database services can be assigned to under-utilized servers where resources are available to help carry heavy loads on the engine. Any node that hosts a database service must be specified in the iPlanet UDS environment definition as supporting a database resource manager (otherwise, a database service will not be installed on the node).

9. Click the Options tab to display the Options dialog:

100 iPlanet Integration Server • Process System Guide • August 2001

Sun Microsystems iPlanet Integration Server 3.0 Process System Manual

Specifications and Main Features

Frequently Asked Questions

User Manual