BusinessWare Administration Guide 4.2.1

BusinessWare
Administration Guide
BusinessWare Version 4.2.1
March 2004
Copyright 1997-2004
Vitria Technology, Inc.
945 Stewart Drive
Sunnyvale, CA 94085-3913
Phone: (408) 212-2700
Fax: (408) 212-2720
All rights reserved. Printed in the USA.
Vitria, BusinessWare, Vitria Collaborative Application, VCA, VCML,

Trading Partner Manager, and XEDI are trademarks or registered
trademarks of Vitria Technology, Inc. All other brand or product names
are trademarks or registered trademarks of their respective companies or
organizations.
This document, as well as the software documented in it, is furnished

under license and may only be used or copied in accordance with the
terms of such license. This product includes technology protected by
U.S. Patent No. 6,338,055 B1.
The information in this document is subject to change without notice.
TABLE OF CONTENTS
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Related Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
BusinessWare Documentation Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
How this Guide Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Command-Line Notation Conventions . . . . . . . . . . . . . . . . . . . . . . xvi
Contacting Vitria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Headquarters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Chapter 1 Introduction to BusinessWare Administration. . . . . . . . 1-1

BusinessWare Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Management Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Web Administration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Command-Line Tools (Utilities) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Installation, Deployment, and Administration . . . . . . . . . . . . . . . . . . . . . 1-3
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Basic Administration Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Starting and Stopping BusinessWare Server . . . . . . . . . . . . . . . . . 1-6
Configuring Additional Parameters for BusinessWare Servers . . . . 1-6
Configuring Additional Parameters for Communicator Servers. . . . 1-6
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Chapter 2 Using the Web Administration Tool . . . . . . . . . . . . . . . . 2-1

How to Start the Web Administration Tool . . . . . . . . . . . . . . . . . . . . . . . 2-1
Web Administration Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
BusinessWare Administration Guide iii

TABLE OF CONTENTS
All Projects View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Project Group View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Project View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Servers View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Clusters View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Administering BusinessWare Servers, Clusters, and Communicator Servers
2-6
BusinessWare Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Communicator Servers (chanserv) . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Administering Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Starting and Stopping Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Undeploying Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Purging Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Setting Project Global Default Properties . . . . . . . . . . . . . . . . . . . 2-16
Administering Project Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Chapter 3 Using the Command-Line Administration Tool . . . . . . . 3-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Configuring BusinessWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Validating Directory Server Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Starting and Stopping BusinessWare In Windows . . . . . . . . . . . . . . . . . 3-3
Starting and Stopping BusinessWare in Unix . . . . . . . . . . . . . . . . . . . . . 3-3
Administering BusinessWare and Communicator Servers . . . . . . . . . . . 3-3
Administering Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Administering Project Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Integration Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Connectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Channels and Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Administering Clusters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Listing Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Administering Performance Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Chapter 4 Security and User Management. . . . . . . . . . . . . . . . . . . . 4-1

Overview of Organizational Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
iv BusinessWare Administration Guide

TABLE OF CONTENTS
Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Security Models in BusinessWare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Directory Server Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Using the BusinessWare Namespace . . . . . . . . . . . . . . . . . . . . . . . 4-6
Summary of the BusinessWare Namespace. . . . . . . . . . . . . . . . . . 4-9
Managing Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Role Groups, Rights, and Access Levels . . . . . . . . . . . . . . . . . . . 4-11
Creating Groups and Users Using Sun ONE Directory Server . . . 4-12
Creating Groups and Users Using Active Directory . . . . . . . . . . . 4-14
Creating Groups and Users Using IBM Directory . . . . . . . . . . . . . 4-16
Administering Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
Caching Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
Required Permissions for BusinessWare Components . . . . . . . . 4-19
BusinessWare Default Security Settings. . . . . . . . . . . . . . . . . . . . 4-19
Setting Up a Guest Credential. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Customizing BusinessWare Security and Access Control . . . . . . 4-22
Best Practices for Setting Access Control . . . . . . . . . . . . . . . . . . . 4-23
Federating BusinessWare 4.x Instances. . . . . . . . . . . . . . . . . . . . . . . . 4-24
Secure Communication Using SSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25
Security Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
Configuring BusinessWare for SSL. . . . . . . . . . . . . . . . . . . . . . . . 4-30
Configuring Your Directory Server to Run Under SSL . . . . . . . . . 4-32
Chapter 5 Administering Databases . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

BusinessWare Database Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Table Names and Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
BPOs and DOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Transaction Manager State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Connector State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Connector Transaction ID Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Timer Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Tasks and Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Configuring IBM DB2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
BusinessWare Administration Guide v

TABLE OF CONTENTS
Increasing Buffer Pool and Table Space . . . . . . . . . . . . . . . . . . . . . 5-6

Avoiding -911 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Configuring MSSQL Server 2000 to Support JTA . . . . . . . . . . . . . . . . . . 5-7
Sybase Configuration Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
XA Configuration for Oracle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Chapter 6 Administering Web Servers . . . . . . . . . . . . . . . . . . . . . . . 6-1

Admin Web Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Configuring the Admin Web Server to Run in SSL Mode . . . . . . . . 6-2
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Web Server/Servlet Engine in Integration Server . . . . . . . . . . . . . . . . . . 6-3
Internal Web Server Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
External Web Server Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Deploying Vitria Web Applications in Web Servers . . . . . . . . . . . . . . . . . 6-9
BusinessWare Task List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Business Cockpit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Web Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Deploying Web Applications in External Web Server Mode . . . . . 6-12
Setting Up Web Applications for Single Sign-On. . . . . . . . . . . . . . . . . . 6-14
Enabling Single Sign-On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Setting Session Time-Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Chapter 7 Administering Business Cockpit . . . . . . . . . . . . . . . . . . . 7-1

Cockpit License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Cockpit Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Cockpit Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Cockpit Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Configuring Cockpit Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Cockpit Server Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Configuring Cockpit Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Changing the Cockpit Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Creating a New Cockpit Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Setting the DISPLAY Environment Variable for Unix. . . . . . . . . . . . . . . . 7-8
Chapter 8 Interoperability with BusinessWare 3.x Installations . . 8-1

Configuring BusinessWare Access Control for Federation . . . . . . . . . . . 8-1
Setting vtprincipal and vtbw3password in Sun ONE Directory
vi BusinessWare Administration Guide

TABLE OF CONTENTS
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Setting vtprincipal and vtbw3password in Active Directory . 8-2
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Setting vtbw3password Using the Web Administration Tool . . . . 8-4
BusinessWare 4.x to BusinessWare 3.x Channel Federation. . . . . . . . . 8-4
Installing the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
BusinessWare 3.x to BusinessWare 4.x Federation . . . . . . . . . . . . . . . . 8-9
Chapter 9 Backing Up and Restoring Files . . . . . . . . . . . . . . . . . . . 9-1

Backup Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
What to Back Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Backing Up Directory Server Files . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Backing Up the Runtime Environment . . . . . . . . . . . . . . . . . . . . . . 9-3
Backup Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Restoring Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Restoration Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Restoring Communicator Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Chapter 10 Command-Line Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

chancheck . . . . . . . . . . . . . . . . . . . . .10-2
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Example Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
cschemagen. . . . . . . . . . . . . . . . . . . . .10-4
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
cstubgen and jstubgen . . . . . . . . . . . . . . . .10-5
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
dtdtotype . . . . . . . . . . . . . . . . . . . . .10-9
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
hidepwd . . . . . . . . . . . . . . . . . . . . . 10-10
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
importfrom3x. . . . . . . . . . . . . . . . . . . 10-11
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
importfrom41x . . . . . . . . . . . . . . . . . . 10-12
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
BusinessWare Administration Guide vii

TABLE OF CONTENTS
logchanview . . . . . . . . . . . . . . . . . . . 10-12
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
registeraction . . . . . . . . . . . . . . . . . 10-13
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
rescomp . . . . . . . . . . . . . . . . . . . . . 10-13
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
showxport . . . . . . . . . . . . . . . . . . . . 10-15
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
startadminwebserver . . . . . . . . . . . . . . . 10-16
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
startservs . . . . . . . . . . . . . . . . . . . 10-16
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
stopadminwebserver . . . . . . . . . . . . . . . 10-17
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
stopservs . . . . . . . . . . . . . . . . . . . . 10-17
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
vtadmin . . . . . . . . . . . . . . . . . . . . . 10-17
Chapter 11 Troubleshooting and Tips . . . . . . . . . . . . . . . . . . . . . . . 11-1
Appendix A Environment Variables, Registry Items, and System Files .

A-1
Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1
Vitria Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1
Additional Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-4
BusinessWare 3.x Environment Variables. . . . . . . . . . . . . . . . . . . .A-4
Windows Registry Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5
System Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-5
Appendix B BusinessWare Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Diagnostic Output Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2
General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2
Diagnostic Output Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2
Example Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-5
Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-5
viii BusinessWare Administration Guide

TABLE OF CONTENTS
Appendix C Scriptable BME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Scriptable BME Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Scriptable BME Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
OpenProject . . . . . . . . . . . . . . . . . . . C-3
DeployProject . . . . . . . . . . . . . . . . . . C-4
ExportProject . . . . . . . . . . . . . . . . . . C-5
InstallProjectModule . . . . . . . . . . . . . . . C-5
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
BusinessWare Administration Guide ix

TABLE OF CONTENTS
x BusinessWare Administration Guide

PREFACE
Welcome to the BusinessWare Administration Guide.

This guide explains how to administer the BusinessWare Server and operating
environment. It also describes how to perform data and transaction management,
and to monitor the system.
This preface contains the following information:

! Audience
! Related Reading
! BusinessWare Documentation Set
! How this Guide Is Organized
! Conventions
! Contacting Vitria
AUDIENCE
This guide is intended for system administrators who are familiar with Windows,
Solaris, HP-UX, and AIX administration.
RELATED READING
Refer to the following documents for information related to the topics in this
manual:
! BusinessWare Installation Guide
! BusinessWare Administration Help (available online)
! Application Administration Help
! BusinessWare Modeling Guide
! BME Help (available online)
BusinessWare Administration Guide xi

PREFACE
BUSINESSWARE DOCUMENTATION SET

The BusinessWare documentation set includes the following manuals:
Table 1 BusinessWare Documentation

Document Description
Read these documents first
BusinessWare Introduction Introduces the BusinessWare product suite and
architecture and describes the key concepts underlying
BusinessWare.
Read this manual first.
BusinessWare Release Provides current information on features, fixes, and
Notes known problems for BusinessWare.
Read this document before installing BusinessWare.
BusinessWare Migration Describes how to migrate a BusinessWare 3.1.x
Guide solution or a BusinessWare 4.1.x solution to
BusinessWare 4.2.1 and provides a conceptual
comparison between those versions of BusinessWare
and BusinessWare 4.2.1.
Read this manual if you wish to migrate a previous
version of BusinessWare to BusinessWare 4.2.1.
BusinessWare Installation Explains how to install BusinessWare and supporting
Guide for Windows third-party products and how to perform initial
configuration on your operating system.
Read this manual before installing BusinessWare.
BusinessWare Installation Explains how to install BusinessWare and supporting
Guide for Unix third-party products and how to perform initial
configuration on your operating system.
Read this manual before installing BusinessWare.
BusinessWare documents
BusinessWare Explains how to administer and manage
Administration Guide BusinessWare.
BusinessWare Describes how to perform basic administration tasks
Administration Help using the BusinessWare Web Administration tool.
Application Administration Describes how to administer the registry service for
Help trading partners; users, groups, and roles for your
BusinessWare solutions; and the logging service.
Access this online help system through the Application
Administration UI.
xii BusinessWare Administration Guide

PREFACE
Table 1 BusinessWare Documentation (Continued)

BusinessWare Performance Describes how to monitor and tune BusinessWare for
Tuning Guide higher performance.
BusinessWare High Describes how to install and configure BusinessWare
Availability Guide for a high availability cluster and how to integrate
BusinessWare with cluster software.
BusinessWare Modeling Describes the BusinessWare application integration
Guide platform that manages the integration lifecycle with an
integrated development environment for designing,
developing, deploying, testing, monitoring, and
analyzing business solutions.
BME Help Describes how to model, debug, and deploy projects in
the BME.
Access this online help system through the
BusinessWare Modeling Environment.
BusinessWare Documents BusinessWares Java and C++ public
Programming Reference APIs.
Business Cockpit Guide Describes how to access and manage process views
using the Cockpit Web interface.
Business Cockpit Help Context-sensitive help that describes how to access
and manage process views using the Cockpit Web
interface.
Business Collaboration Describes how to build a Business Collaboration
Guide solution using BusinessWare. Includes details on the
Registry Service, messaging, and trading protocols
and transports.
BusinessWare Transformer Describes how to use the BusinessWare Transformer
Guide to transform input events of one type to an output event
of a different type.
BusinessWare Task List Describes how to create the BusinessWare Workflow
Guide Web interface and how to use the BusinessWare Task
List as a performer, supervisor, or manager.
BusinessWare Glossary Defines key terms associated with BusinessWare.
BusinessWare Administration Guide xiii

PREFACE
Table 1 BusinessWare Documentation (Continued)

Email Connector Guide Describes how to configure and use the Email
Connector installed with this release of BusinessWare.
File Connector Guide Describes how to configure and use the File Connector
installed with this release of BusinessWare.
FTP Connector Guide Describes how to configure and use the FTP
HTTP Connector Guide Describes how to configure and use the HTTP
HOW THIS GUIDE IS ORGANIZED

This book contains the following sections:
Table 2 Contents of this Guide

Section Contents
Chapter 1, Introduction to Provides an introduction to the BusinessWare
BusinessWare Administration system and describes the management tools
available for use.
Chapter 2, Using the Web Provides a brief overview of how to use the Web
Administration Tool Administration Tool.
Chapter 3, Using the Describes how to use the vtadmin utility.
Command-Line Administration
Tool
Chapter 4, Security and User Describes how to set up secure transactions and
Management access control in a BusinessWare environment.
Chapter 5, Administering Describes how to administer databases used by
Databases BusinessWare.
Chapter 6, Administering Web Describes how to administer and configure Web
Servers servers in a BusinessWare environment.
Chapter 7, Administering Describes how to administer and configure
Business Cockpit Business Cockpit.
Chapter 8, Interoperability with Describes how to federate BusinessWare Servers.
BusinessWare 3.x Installations
Chapter 9, Backing Up and Describes how to back up and restore
Restoring Files BusinessWare information.
Chapter 10, Command-Line Describes BusinessWare command-line tools.
Tools
xiv BusinessWare Administration Guide

PREFACE
Table 2 Contents of this Guide (Continued)

Section Contents
Chapter 11, Troubleshooting Provides troubleshooting and tip information.
and Tips
Appendix A, Environment Describes the environment variables and registry
Variables, Registry Items, and items available with BusinessWare.
System Files
Appendix B, BusinessWare Describes BusinessWare log files and how to set
Log Files the diagnostic output specification.
Appendix C, Scriptable BME Describes the command-line utility used to
deploy a project, given sources extracted
from a versioning system.
CONVENTIONS
This manual uses the following conventions:
! Monospace
Specifies file names, object names, and programming code.
Example: C:\VTlicenses
! Italics
" Identifies a variable.
Example: installdir/bin/unix_platform, where
installdir indicates the directory where BusinessWare is installed and
unix_platform indicates the Unix platform, such as Solaris, HP-UX,
or AIX.
" Indicates a value that you must enter within examples and command
syntax.
Example: java com.vitria.rta.AnalyzerUtil -n servername
" Introduces new terminology, highlights book titles, and provides
emphasis.
Example: An operation is a defined action that is meant to be applied to a
given class of software objects.
! Bold
Highlights items and indicates specific items in a graphical user interface
(GUI).
Example: From the list, select the Properties item.
BusinessWare Administration Guide xv

PREFACE
! Path names
" This document uses the variable installdir to indicate the directory where
BusinessWare is installed. On Windows, the default installation directory
is C:\Program Files\Vitria\BW41. On Unix, the default
installation directory is /usr/local/bw41.
" While BusinessWare is supported on multiple operating systems, path
names are displayed only in the Windows backslash format.
Example for Windows systems:
samples\communicator\javaflow\anypub.java
" If you are operating in a Unix environment, change to the forward slash
format.
Example for Unix systems:
samples/communicator/javaflow/anypub.java
" Internet URLs follow the standard forward slash convention.
Example:
http://www.vitria.com
COMMAND-LINE NOTATION CONVENTIONS

This manual uses the following command-line notation conventions:
! { } Braces
Identifies a set of items from which you must choose one.
Example: java com.vitria.rta.AnalyzerNamedViewUtil -n view
{ -i file name | -x file name }
! [ ] Brackets
Identifies an optional item.
java com.vitria.rta.AnalyzerSchemaUtil -n schema-folder
{ [-o ODL-file ... -o ODL-filen | -i schema-file ]
[-x schema-file ] }
! | Or Operator
Separates items from which you may choose one.
Example: java com.vitria.rta.AnalyzerNamedViewUtil -n view
{ -i file name | -x file name }
xvi BusinessWare Administration Guide

PREFACE
CONTACTING VITRIA
If you have any questions regarding Vitria or any of the Vitria products, please
contact Vitria using the resources listed in this section.
HEADQUARTERS
Vitria Technology, Inc.
945 Stewart Drive
Sunnyvale, CA 94085
1-408-212-2700
http://www.vitria.com
TECHNICAL SUPPORT
Vitria Technical Support provides comprehensive support for all Vitria products
through our Technical Support Web site:
http://help.vitria.com (login and password required)
If you need a login for help.vitria.com, please send your request to:
contractadmin@vitria.com
Each customer who has purchased a support contract has one or more designated
individuals who are authorized to contact Vitria Technical Support. If you have
questions about using the BusinessWare products, please have a designated
person at your site open a case with Vitria Technical Support.
DOCUMENTATION
If you have any comments on the documentation, please contact the Technical
Publications group directly:
documentation@vitria.com
We would like to hear from you.
BusinessWare Administration Guide xvii

PREFACE
xviii BusinessWare Administration Guide

1 1 INTRODUCTION TO BUSINESSWARE
ADMINISTRATION
The BusinessWare Administration Guide provides the necessary information to

configure and manage your BusinessWare solution. For an overview of the key
features of BusinessWare, see the BusinessWare Introduction. This chapter
provides an overview of the following topics:
! BusinessWare Subsystems
! Management Tools
! Installation, Deployment, and Administration
! Basic Administration Activities
! Environment Variables
BUSINESSWARE SUBSYSTEMS
This section provides an overview of the basic BusinessWare subsystems. See
Management Tools on page 1-2 for information on the tools available to
manage these subsystems.
! BusinessWare Server (BServ)controlling process that starts the other
BusinessWare systems. The BusinessWare Server monitors all other services,
such as the Communicator Server and Integration Servers, and sends
notification when there is a service failure.
! Communicator Server (chanserv)BusinessWares asynchronous event
delivery mechanism that enables publish-subscribe communication.
Publishers push events to one or more channels/queues and subscribers
retrieve the events.
! Integration Serverserver that hosts the integration models that customers
create using the BusinessWare Modeling Environment (BME).
! Java servlet engine and Web Serverthe BusinessWare Runtime
Environment provides an integrated Web server and servlet engine that
enables the Web-based administration of all BusinessWare components.
See the BusinessWare Installation Guide for information on supported
products and other requirements.
BusinessWare Administration Guide 1-1

INTRODUCTION TO BUSINESSWARE ADMINISTRATION
Management Tools
! Directory Serverserver that provides a central repository for all runtime

objects within a BusinessWare system. Users and groups that have access to
BusinessWare components also reside in the directory server. See Chapter 4,
Security and User Management for more information on directory servers.
See the BusinessWare Installation Guide on supported products and other
requirements.
! Relational Database Management System (RDBMS)persistence for all
business objects created and used in a BusinessWare solution. BusinessWare
supports several database management systems.
See the BusinessWare Installation Guide for version numbers and other
requirements.
MANAGEMENT TOOLS
BusinessWare includes a Web-based graphical user interface (GUI), which is the
Web Administration Tool, and command-line tools (utilities).
WEB ADMINISTRATION TOOL

The Web Administration Tool lets administrators manage or monitor the
BusinessWare Runtime Environment and the solutions built and deployed to this
environment, using a Web browser from anywhere on the network. The Web
Administration Tool:
! Displays information about the objects in the BusinessWare namespace in the
directory server.
! Connects to the BusinessWare Runtime Environment by means of a Java
servlet engine.
! Uses a Web browser so administrators can manage the runtime environment
anywhere on the network.
Note: When you install BusinessWare, you also must install the Tomcat servlet
engine to support this tool.
For more information on the using the BusinessWare Web Administration tool,
see Chapter 2, Using the Web Administration Tool.
COMMAND-LINE TOOLS (UTILITIES)

BusinessWare also provides command-line tools (utilities) to manage your
system. See Chapter 10, Command-Line Tools.
1-2 BusinessWare Administration Guide

Installation, Deployment, and Administration
Of these, the vtadmin command-line tool is used most often because it:
! Provides a versatile and consistent way to perform common administrative
operations on a variety of BusinessWare objects, and enables you to perform
these operations with scripts.
! Provides dozens of functions including starting, stopping, and checking the
status of BusinessWare Servers and channels/queues.
! Displays lists of all nodes, servers, channels, subscribers, or publishers where
you can deploy and undeploy projects.
Note: BusinessWare administrators must have sufficient privileges to
perform administration operations.
See Chapter 3, Using the Command-Line Administration Tool for more
information.
INSTALLATION, DEPLOYMENT, AND ADMINISTRATION

A complete BusinessWare solution consists of an installation, deployment, and
administration phases. While the three phases may overlap, different tasks are
required for each. This section describes the components that are configured in
each of these phases to provide you with a better understanding of
administrationthe focus of this guide.
INSTALLATION
The BusinessWare Installer installs and configures the BusinessWare subsystems
including bundled third-party software that you choose to install and embedded
third-party software. During the installation process, you can manually configure
various items including:
! Destination location of BusinessWare runtime, BusinessWare Modeling
Environment, and Software Development Toolkit (SDK) files
! Various directories, including:
" Licenses directory
" JDK directory
" JRE directory
" .vtparams file location
! Windows service account
! Web server ports
! Environment variables

Installation, Deployment, and Administration
! Various areas of BusinessWare, such as multiple server pairs
Directory Server-Related Items

Also during installation, the BusinessWare schema and several other objects are
installed into the directory server. You must manually configure the following
directory server-related items:
! Domain name of your network
! Directory server host name
! Directory server Directory Manager account
! Directory server port
! Namespace root
! BusinessWare user account in the directory server
! Directory server Groups container
! Directory server Users container
For more information on installation, see the BusinessWare Installation Guide.
For more information on directory servers, see Chapter 4, Security and User
Management.
DEPLOYMENT
Deployment is the process by which a BusinessWare project (created in the
BusinessWare Modeling Environment) is configured and partitioned to run in the
BusinessWare Runtime Environment.
The BusinessWare Modeling Environment provides a Deployment Tool that

automatically does the packaging, preparation, and moving to the repositorya
directory serverfor you. The deployment tool itself is an editor within the BME
that enables you to deploy a BusinessWare project as a fully functioning
BusinessWare application.
Deployment activities include:

! Identifying and locating the project that needs to be deployed
! Accessing the runtime environment
! Creating a Deployment Configuration component for the project by creating
one from the template in the BME:
" Configuring the components in the project

Basic Administration Activities
" Partitioning the components across the server environment

! Deploying the configured, partitioned project
! Configuring the security system, including:
" TCP/IP
" SSL
Note: The directory server is updated with the appropriate project information
during deployment.
For more information on deployment, see the BusinessWare Modeling Guide.
ADMINISTRATION
During administration you should monitor, debug, perform diagnostics, and
configure and reconfigure your BusinessWare solution as needed. The list below
is a high-level view of the activities that you can perform during administration:
! Viewing and changing various properties of BusinessWare projects and
servers, including:
" Projects
" Businessware Servers
" Integration Servers
" Communicator Server
" Channels/queues
! Monitoring BusinessWare via diagnostic logs
! Configuring Web servers
! Setting up BusinessWare Task List
For more information on administration, access the BusinessWare Administration

Help.
BASIC ADMINISTRATION ACTIVITIES

This section describes how to perform basic administration activities. More
detailed administration information is discussed in the subsequent chapters.

Basic Administration Activities
STARTING AND STOPPING BUSINESSWARE SERVER

Upon startup, every BusinessWare Server automatically starts and pairs itself with
a Communicator Server. A Communicator Server shuts down when its
corresponding BusinessWare Server is shut down. A BusinessWare Server also
shuts down when its corresponding Communicator Server is shut down or cannot
be started.
You can start or stop the BusinessWare Server using the Services control panel
(go to Windows Control Panel > Administrative Tools > Services).
You may also start and stop BusinessWare Servers on Unix platforms, using
command-line scripts. See startservs on page 10-16, stopservs on
page 10-17, startadminwebserver on page 10-16, and
stopadminwebserver on page 10-17.
Note: Projects must be manually restarted if the BusinessWare Server is stopped
and restarted. Projects are never automatically restarted.
CONFIGURING ADDITIONAL PARAMETERS FOR BUSINESSWARE

SERVERS
Use vtadmin getproperties bserv and vtadmin setproperties
bserv to view or change the settings for your BusinessWare Server. See
Chapter 3, Using the Command-Line Administration Tool, or enter the
command vtadmin help bserv for more information on these commands.
CONFIGURING ADDITIONAL PARAMETERS FOR COMMUNICATOR

SERVERS
Communicator Servers are configured when the BusinessWare Server activates
an instance of the Communicator Server. Use either vtadmin or the Web
Administration tool to configure additional Communicator Server parameters.
For vtadmin, use vtadmin getproperties chanserv and vtadmin

setproperties chanserv to view or change the settings for your
Communicator Server. See Chapter 3, Using the Command-Line Administration
Tool, or enter the command vtadmin help chanserv for more
information on these commands. See also Chapter 2, Using the Web
Administration Tool.

Environment Variables
ENVIRONMENT VARIABLES
BusinessWare Servers and Communicator Servers use the system environment
variables given in Appendix A, Environment Variables, Registry Items, and
System Files. These variables are specified in your Windows Control Panel
under System > Advanced.
Note: You must stop the server before configuration, then restart the server for
the modifications to take effect. Generally, the environment variables are set to
default values as part of the installation process before the very first launch of a
BusinessWare Server.


2 2 USING THE WEB ADMINISTRATION TOOL
The BusinessWare Web Administration tool is a Web-based GUI for

administrators who manage or monitor the BusinessWare Runtime Environment
and the solutions to be built in and deployed to this environment.
Topics discussed in this chapter include:

! How to Start the Web Administration Tool
! Web Administration Views
! Administering BusinessWare Servers, Clusters, and Communicator Servers
! Administering Projects
! Administering Project Components
Note: You also can complete many of the activities discussed in this chapter
using the vtadmin command-line tool. For more information on vtadmin, see
Chapter 3, Using the Command-Line Administration Tool.
IMPORTANT: This chapter gives an overview of the Web Administration Tool

and describes major tasks. For more detailed information on the individual
properties that can be viewed and/or set using the Web Administration Tool, see
the BusinessWare Administration Help by clicking on the Help icon in the tool.
HOW TO START THE WEB ADMINISTRATION TOOL

To start the Web Administration Tool on Windows, select Start > Programs >
Vitria BusinessWare 4.2.1 > BusinessWare Web Administration.
You may also start the Web Administration tool through your browser by entering
the URI with the appropriate port number you configured during installation, such
as http://localhost:8080. If you enabled SSL for the Web Administration
tool (see Admin Web Server on page 6-1), your URI might be
https://localhost:8443.

USING THE WEB ADMINISTRATION TOOL
Web Administration Views
WEB ADMINISTRATION VIEWS

The BusinessWare Web Administration interface is designed using hierarchical
views. You can start with a top-level view and drill down to get more detail, or
you can use the Namespace View to jump directly to a specific view with fewer
clicks.
There are several views which comprise the BusinessWare Web Administration
tool, many of which can be accessed from more than one point. The following
views are primary views, in that they serve as good starting points for accessing
information:
! All Projects View
! Project View
! Servers View
ALL PROJECTS VIEW

The All Projects View is the first view displayed after logging in to the
BusinessWare Web Administration tool. See Figure 2-1.
Figure 2-1
Figure 2-1 The All Projects View

You can only start and stop projects or view the properties for the items displayed
in the executables list.
You can do the following from this view:
! All Items ViewClick the All Items View icon to display a resource-
centric view instead of a project-centric view.
! Log OutClick the Logout icon to log the current user out of the
BusinessWare Web Administration tool.
! View HelpClick the Help icon to display help for the BusinessWare
Web Administration tool.
! Enable Auto RefreshSelect the Auto Refresh box to enable
your view to be automatically refreshed.
! Start and Stop ProjectsClick the Start or Stop buttons to
start or stop the selected projects and all services associated with them. See
Starting and Stopping Projects on page 2-14 for more information.
! Set Project Global Default PropertiesClick the Properties button
to display the Project Global Defaults dialog box for the selected
project. Exactly one project must be selected. See Setting Project Global
Default Properties on page 2-16 for more information.
! Undeploy ProjectsThe Undeploy button allows you to
undeploy one selected project at a time. See Undeploying Projects on
page 2-14 for more information.
! View LogsThe Log Viewer allows you to view log files associated with text
or binary diagnostic loggers in the All Projects View. Select a component from
the All Projects View and click the View Logs button . Select the
logger you want to view and click OK.
The top part of the Log View displays logger-specific options to choose from
and the bottom displays the log entries. A channel logger shows you the
number of log entries in the channel. A text file logger displays the number of
log entries in the file and lets you select a range of entries to display.
The Display Last First option displays messages in reverse order (last
received message is displayed first). Clicking Update refreshes the displayed
entries. Clicking the arrows at the bottom of the window jumps you to the
beginning or end of the log. Clicking Cancel closes the logger.

! Configure BusinessWareClick the BW Config button to

display the BusinessWare Configuration dialog box. This dialog enables you
to configure properties, such as a Guest User ID and password, BusinessWare
3.x password, maximum directory server entry size, and security settings. The
Guest User ID and password allow external BusinessWare clients (such as
external ORBs and RMI clients) to access BusinessWare. See Setting Up a
Guest Credential on page 4-21 for more information. The BusinessWare 3.x
password is used for interoperability between BusinessWare 3.x and
BusinessWare 4.x. See Chapter 8, Interoperability with BusinessWare 3.x
Installations, for more information.
! Purge ProjectsClick the Purge Project button to purge
components and connectors within a project. See Purging Projects on
page 2-15 for more information.
! Display Project DetailsClick on a project link in the Name column to
display the Project View for that project. See Project View for more
information.
PROJECT GROUP VIEW

! Click a link in the Server column to display the Servers View for that project
and BusinessWare Server or Cluster.
! For the Project Group Type, start the projects under the project group.
! Stop the projects under the project group.
! Check the status of projects under the project group.
! List all the projects in a project group or child project groups or list all project
groups if no project group is specified.
! Display the information available for the project group.
PROJECT VIEW
The Project View is displayed when you select a Project link from All Projects
View. A list of all BusinessWare Servers and Clusters that are used by the project
is displayed. The list includes additional details, such as the BusinessWare Server
status, server type, server name, and the server directories.


! Click Properties to display the BusinessWare Server Properties or Cluster
Properties dialog box for the selected item. Exactly one BusinessWare Server
or Cluster must be selected. See BusinessWare Servers on page 2-6 and
Clusters on page 2-8 for more information.
! Click on a link in the server column to display the Servers View for that project
and BusinessWare Server or Cluster.
SERVERS VIEW
The Servers View displays when you select a BusinessWare Server link from the
Project View. This view lists all of the services associated with the selected
project that are configured to run on the selected server.

! Click Start to start the selected services, which can be Integration Servers.
This operation is not applicable to Communicator Servers.
! Click Stop to stop the selected service(s).
! Click Properties to display the Server Properties dialog box for the selected
server (Integration Server, Communicator Server). Exactly one server must be
selected.
! Click on a link in the Name column to display the view specific to the server
type (for example, Integration Server, Communicator Server).
CLUSTERS VIEW
The Clusters View is displayed when you select a Cluster link from the Project
View. This view lists all of the master and slave nodes in the cluster.

! Click Start to start the selected servers.
! Click Stop to stop the selected servers.
! Click Properties to display the Server Properties dialog box for the selected
Integration server. Exactly one server must be selected.
! Click on a link in the Name column to display the Server View for the
Integration server.

ADMINISTERING BUSINESSWARE SERVERS, CLUSTERS, AND

COMMUNICATOR SERVERS
Generally, servers are first configured during the BusinessWare installation
process. You can reconfigure servers at any time after initial installation.
However, after initial installation and server launch, configuration tasks must take
place in a specific order for modifications to take effect. This section describes the
tasks required to configure BusinessWare and Communicator Servers, and the
order in which they must be implemented after initial installation.
Execute post-installation configuration tasks for the BusinessWare or

Communicator Servers in the following order:
1. Configure a set of BusinessWare or Communicator Server attributes through
the Web Administration tool.
2. Stop the BusinessWare Server. This automatically stops its corresponding
Communicator Server.
3. Modify environment variables using the Windows Control Panel.
4. Restart the BusinessWare Server. This automatically restarts its corresponding
For information on how to start and stop the BusinessWare Server, see Starting
and Stopping BusinessWare Server on page 1-6.
Note: The sections below show you how to access the BusinessWare Server and
Communicator Server properties through the All Projects View. If no projects
are deployed that use the server you want to configure, you can access those
properties by clicking the All Items View icon. The bserv properties are
available by following the BusinessWare Servers > bserv name link. The
chanserv properties are available by following the BusinessWare Servers >
bserv name > Services > chanserv link. Click on the name of a server to display
the property view.
BUSINESSWARE SERVERS
To set or change the attributes for the BusinessWare Server:
1. On the All Projects View page, click on a project name under Executable
Projects.
2. On the Project View page, select a BusinessWare Server and click Properties
to make the desired changes. See Figure 2-2.

Figure 2-2
Figure 2-2 Properties for bserv1
You can view or change the following BusinessWare Server properties:

" Host Namehost name where the bserv will run (read only).
" Port Numberport on which the server will listen for requests.
" Statistics Channel Pathpath to Statistics Channel.
" Max Threadsmaximum number of threads used by the server to handle
requests and spawn.
" Statistics Log Intervaltime interval in seconds at which the statistics will
be generated for each component in the server.
" Java Optionsstandard Java command-line options (read only).
3. On the BusinessWare Server Properties page, click the Diagnostic Log
Trace Level tab to view or change the following BusinessWare Server
logging properties (see Figure 2-3):
" Global Trace Levelsets the level of the log tracing for the process.
" Orb Trace Levelsame as above.
" Thread Trace Levelsame as above.
" Transport Trace Levelsame as above.
" Type System Trace Levelsame as above.

Figure 2-3
Figure 2-3 Diagnostic Log Trace Level
CLUSTERS
To set or change the attributes for a Cluster:
Projects.
2. On the Project View page, select a Cluster and click Properties to make the
desired changes.
You can view and/or change the following Cluster properties:

! Router Class Namethe router class for the routing policy set during cluster
configuration. For the default routing policy (Round Robin), the router class
name is com.vitria.container.client.RoundRobinCallRouter.
! Refresh Intervaltime interval (in seconds) that the cluster checks for
changes to slave nodes and properties.

COMMUNICATOR SERVERS (CHANSERV)

To set or change the attributes for the Communicator Server:
Projects.
2. On the Project View page, click on the name of your BusinessWare Server.
See Figure 2-4.
Figure 2-4
Figure 2-4 Servers
3. On the Servers page, select the chanserv checkbox, and click Properties to
make the desired changes. See Figure 2-5.

Figure 2-5
Figure 2-5 Properties for chanserv
Note: Some properties (for example, the current DAT file size) are not
available unless the Communicator Server is running.
Note: Port changes do not take effect until the Communicator Server is
restarted.
You can view or change the following Communicator Server properties:
" IP AddressIP address of the server (read only).
" Version Infoversion number of the Communicator Server (read only).
" Port Numberport on which server listens for requests.
" Wait Limittime in seconds that a channel will wait for a reply from a
subscriber (default value for new channels/queues).
" Batch Event Sizenumber of events a publisher will send before verifying
the events have been received (default value for new channels/queues).
" Max Threadsmaximum number of worker threads that the server should
use.
4. Click the Multicast Properties tab to make the desired changes. See
Figure 2-6.

Figure 2-6
Figure 2-6 Properties for chanserv: Multicast Properties
Multicast properties include:

" First Multicast Addressfirst available IP multicast address.
" Last Multicast Addresslast available IP multicast address.
" First Multicast Portfirst available multicast port number.
" Last Multicast Portlast available multicast port number.
" Last Multicast Flow Ratemulticast flow rate for Channels.
5. Click the Diagnostic Log Trace Level tab to make the desired changes. See
Figure 2-7.

Figure 2-7
Figure 2-7 Properties for chanserv: Diagnostic Log Trace Level
Diagnostic Log Trace Level properties include:

6. Click the Expert tab to make the desired changes. See Figure 2-8.

Figure 2-8
Figure 2-8 Properties for chanserv: Expert
Expert properties include:

" Current .dat File Sizedisplays the number of bytes currently in use for
the servers .dat file (read only).
Note: The .wal file is linked to the .dat file, and its size is set
during installation. Please refer to Chapter 2, Installing
BusinessWare, in the BusinessWare Installation Guide for Windows
or the BusinessWare Installation Guide for Unix.
" Max .dat File Sizemaximum amount of data in bytes in the channel
event data file. The largest size for the maximum is 4 terabytes.
" Max .wal File Sizemaximum amount of data in bytes in the write-
ahead log file. The size should be approximately three times the size of the
largest planned transaction. Do not set the .wal file too large because the
Communicator server requires about twice this amount of memory.
" Warning Thresholdwarning messages generated when the amount of
data in the servers data file reaches a percentage of the maximum log size.
" Commit Historylifetime in seconds of a transaction commit record.
" Publisher Prune Timetime in seconds that a sub-channel created by
addPub or addNamedPub can remain idle before it is deleted.

Administering Projects
" Active Sub Prune Timetime in seconds that a channel can remain idle
before Communicator asks all subscribers to that channel to acknowledge
receiving events (default value for new channels/queues).
" Inactive Sub Prune Timepolling interval (in seconds) for determining
whether subscribers to an inactive channel are still active (default value for
new channels/queues).
" Transaction Timeoutlength of time in seconds a transaction is allowed
to run.
" Hop Limitmaximum hop count an event is allowed to have.
ADMINISTERING PROJECTS
This section describes how to administer projects from the All Projects View.
STARTING AND STOPPING PROJECTS

To start a Project:
1. Select the checkboxes associated with the projects you want to start.
2. Click the Start button.
All selected projects and all of the services associated with them are started.
To stop a Project:
1. Select the checkboxes associated with the projects you want to stop.
2. Click the Stop button.
All selected projects and all of the services associated with them are stopped.
Note: Projects must be manually restarted if BusinessWare stops or there is a
system problem. Projects are never automatically restarted. You may want to
create a start-up script using the vtadmin start project command. See
Administering Projects on page 3-5.
UNDEPLOYING PROJECTS
To undeploy a project:
1. Select the project in the All Projects View and click the Undeploy button.
2. In the Shared Resources View that is displayed, select the shared resources
that you would like to be removed during undeploy. By default, all resources
are selected for removal.

3. Click the Undeploy button.
PURGING PROJECTS
Various objects within a project, such as source connectors, target connectors,
process models, and channels/queues, have persistent state that at times you may
want to purge.
Note: The Purge command stops the Integration Server in which the project
runs.
To purge components and connectors within a project:
1. Select the project in the All Projects View and click the Purge Project button.
2. In the Purge Project View that is displayed, select the components and
connectors you want to purge. See Figure 2-9.
Figure 2-9
Figure 2-9 Purge Project

a. Select the components from the displayed list. The BPOs and timers
associated with the selected components will be deleted. The Data Objects
(DO) associated with the component will not be deleted unless you check
the Delete DOs box.
b. Select the connectors you want to purge. Select Purge Channels to purge
the channels associated with the selected connectors. Select Purge Queues
to purge the queues associated with the selected connectors.
c. Click the Purge button.
SETTING PROJECT GLOBAL DEFAULT PROPERTIES

You can view or change the following Project Global Default properties by
selecting a project and clicking Properties. See Figure 2-10.
Figure 2-10
Figure 2-10 Project Global Defaults
Project Global Default properties include:

! Statistics Log Intervalthe time interval in seconds at which the statistics are
generated for each component in the server.
! Workflow Audit Enabledis BusinessWare Task List Auditing enabled.

Administering Project Components
! Workflow Audit Channelthe channel on which BusinessWare Task List

audit information will be published if enabled.
! Web Server Namespecifies the Web server used to display information to
Supervisors and Performers when an activity is running (read only).
! Mail Hostspecifies the name of the mail host that will be sending email
notification to Model Supervisors, Activity Supervisors, and Performers (read
only).
! Timer Load Durationspecifies the amount of time in seconds during which
timers can load from the database upon recovery.
! Timer Cache Sizespecifies the maximum size of the cache that contains
loaded timers.
! Commit Retry Countsets the number of times to retry on recovery before
stopping the project as a result of commit failure.
! Ignore Source Connector Errorscan be toggled to true or false.
ADMINISTERING PROJECT COMPONENTS

Projects are the top-level entity for BusinessWare solutions and contain
components, such as Integration Servers, connectors, channels, queues, and
proxies. This section addresses configuring Integration Server properties. For
information about properties for other components, refer to the Web
Administration tool help.
To set or change the attributes for an Integration Server:
1. On the All Projects page, click on a project name under Executable Projects.
2. On the Project View page, click on the name of your BusinessWare Server.
3. On the Servers page, select the Integration Server and click the Properties
button.
WARNING: Changing property values may corrupt your deployed project.

Always back up existing settings using the command vtadmin
getproperties project -all <project> <xml path> prior to making
changes. Backing up the properties allows you to restore your original settings
without having to redeploy your project.

You can view or change the following Integration Server properties by clicking
on the appropriate tab and entering values in the fields. See Figure 2-11.
Figure 2-11
Figure 2-11 Integration Server Properties
Integration Server properties include:

! Properties
" Commandcommand executable to start the process.
" Java Optionsstandard Java command-line options.
" Extra Classpathpart of classpath that will be prepended to the current
user $CLASSPATH.
" Port Numberport on which the server listens for requests.
" Max Threadsspecifies the number of threads allocated to the process in
the default thread pool.
" Enable Debugging and Animationadds properties to the command line
to enable debugging and animation.
" Debug and Animation Portport to which debugger will connect.

" Persistent Storename of the persistent store (read only). RStore

Persistence Storage is broken up into two types that can be chosen for each
Integration Server:
# Cache Only (no database required)
# RDBMS
" Enable Web ServerNone, Internal, or External (read only).
" Directory Server Connection Poolnumber of threads used for directory
server connections.
" Directory Server Connection Timeouttime in seconds before the
attempted connection times out.
! Diagnostic Log Trace Level
" Container Trace Levelsame as above.
" Connector Trace Levelsame as above.
" Process Model Trace Levelsame as above.
" Process Query Trace Levelsame as above.
" Transformer Trace Levelsame as above.
" Cockpit Trace Levelsame as above.
" Connection Manager Trace Levelsame as above.
" Transaction Manager Trace Levelsame as above.
" RStore Trace Levelsame as above.
" Type System Trace Levelsame as above.
" Web Server Trace Levelsame as above.
" Logging Service Trace Levelsame as above.
" Document Store Service Trace Levelsame as above.
" Registry Service Trace Levelsame as above.
" Security Service Trace Levelsame as above.
! Connection Manager
" Max Connectionsmaximum number of connections for each Connection
Factory.

" Connection Request Timeouttime in seconds to wait before freeing a

connection.
" Unused Connection Timeouttime in seconds to wait before freeing an
unused connection.
! Transaction Manager
" Duration Timeouttime in seconds to wait for commit before rollback.
" Inactivity Timeouttime in seconds to wait during an inactive period
before rollback.
! Diagnostic Loggers
Select the logger you want and click the Properties button.
" Text File Logger
# File Namespecifies the fully qualified name of the file to which to
print log messages.
# File Sizesets the maximum size of a log file.
# Number of Backupssets the number of log backup files to create
before purging old data.
# Flush After Messagespecifies whether to write to the log file after a
message is received.
# Source Prefixspecifies whether to include the module that sent the
message in the log.
# Message ID Prefixspecifies whether to include the message resource
name in the log.
# Thread ID Prefixspecifies whether to include the current thread ID
in the log.
# Time Prefixspecifies whether to log the time a message occurs.
# Short Time Prefixspecifies whether to log the short version of the
time at which the message occurs.
# Category Prefixspecifies whether to include the message category in
the log output.
# Encodingspecifies the output encoding for localization.
" Binary File Logger
# File Namespecifies the fully qualified name of the file to which to
print log messages.
# File Sizesets the maximum size of a log file.
# Number of Backupssets the number of log backup files to create
before purging old data.

# Flush After Messagespecifies whether to write to the log file after a

message is received.
" Channel Logger
# Channel Namespecifies the name of the channel to which logging
information is sent.
# Event Batch Sizespecifies the number of events to send before the
server checks to see if a subscriber channel has received its events.
! Persistence
Note: If the server uses Cache instead of RDBMS, then there are no
properties listed.
" Database Resource Namename of the database resource.
" Truncate Stringsenables BusinessWare to truncate string values
(VARCHAR) if the strings are longer than the databases supported
column size.
" Serialize Blobcontrols how the object data is stored in the database. If
OFF, objects will be mapped using the normal object-relational mappings.
If ON, objects will be mapped as key/blob pairs.
" Prefixspecifies the prefix of internal and generated table names.
" Special Charspecifies the separator in generated table names and field
names.
" Class Separatorspecifies the separator in non-generated table names.
! Web Server (internal)
Note: These properties are listed if the Integration servers Enable Web
Server property is set to Internal.
" HTTP Compression Typethe type of compression to enable on the Web
server: off, on, or force. The default is off.
" ProtocolHTTP, HTTPS, or both
" HTTP PortHTTP port on which the Web server listens for requests.
" HTTPS PortHTTPS port on which the Web server listens for requests.
" Max Threadsmaximum number of threads.
" Max Connectionsspecifies the maximum number of connection requests
that are queued for the Web server.
" Connection Timeoutamount of time in seconds an inactive request
connection remains open.
" Event Listener Classlistener class for the Web server events that can be
used to implement a URL stream handler for specific protocols.

! Web Server (external)
Note: These properties are listed if the Integration servers Enable Web
Server property is set to External.
" Redirection ProtocolAJP (currently read only property).
" Redirection Portport on which the Web server listens for requests.
" Max Threadsmaximum number of threads.
" Max Connectionsspecifies the maximum number of connection requests
that are queued for the Web server.
" Connection Timeoutamount of time an inactive request connection
remains open.
" Event Listener Classlistener class for the Web server events that can be
used to implement a URL stream handler for specific protocols.

3 3 USING THE COMMAND-LINE
ADMINISTRATION TOOL
The vtadmin command-line utility provides a versatile and consistent way to

perform common administrative operations on a variety of BusinessWare objects.
This chapter describes the vtadmin utility.
Topics include:
! Overview
! Configuring BusinessWare
! Validating Directory Server Schema
! Starting and Stopping BusinessWare In Windows
! Starting and Stopping BusinessWare in Unix
! Administering BusinessWare and Communicator Servers
! Administering Projects
! Administering Project Components
! Administering Clusters
! Listing Proxies
! Administering Performance Monitoring
! Examples
OVERVIEW
System administrators interact with several different kinds of BusinessWare
objects: servers, channels, etc. With vtadmin, you can operate on a single object
or multiple objects of the same or different types in a unified way. For example,
you can start multiple Integration Servers with a single vtadmin invocation.
Note: To execute vtadmin, you must have permissions appropriate for the
action you ask vtadmin to perform.

USING THE COMMAND-LINE ADMINISTRATION TOOL
Configuring BusinessWare
SYNTAX
The most frequently used form of the vtadmin utility is:
vtadmin command component_type <path>
Specify the three arguments as follows:

! Use command to specify the operation you want to perform, for example,
start or listall.
! Use component_type to specify the kind of object you want the action
performed on, for example, server or bserv.
Note: The command and component_type parameters are not case sensitive.
! Use <path> to specify the LDAP Distinguished Name (DN) of the
BusinessWare entry to which the command should be applied. The DN is
relative to the BWROOT specified in VTPARAMS. The <path> can be specified
either in DN syntax or by using a pathname separated with slashes (/).
Example: The following pathnames are equivalent:
cn=server,cn=IntegrationServer,cn=bwserver,cn=Servers
/Servers/bwserver/IntegrationServer/server
Example: To obtain the status of Integration Server Int1 at path
/Servers/bwserver/IntegrationServer/server:
> vtadmin check server /Servers/bwserver/
IntegrationServer/server/Int1
You can obtain help on the vtadmin utility using the following syntax:
vtadmin help [component_type]
The optional component_type argument narrows the help to the component type
you specify; otherwise, vtadmin displays help for the available component
types.
CONFIGURING BUSINESSWARE
To configure BusinessWare using vtadmin, use the following
commands:
! vtadmin getinfo bwconfig
Shows directory server configuration information.

Validating Directory Server Schema
! vtadmin update bwconfig [-BW3xPassword <password>]

[-maxsize <maxsize>] [-GuestUser <user name>
-GuestPassword <password>] [-security <encryption>]
Modifies the directory server configuration information. See All Projects
View on page 2-2 for more information.
VALIDATING DIRECTORY SERVER SCHEMA

To validate your directory server schema:
! vtadmin check schema
Validates the schema on the directory server.
STARTING AND STOPPING BUSINESSWARE IN WINDOWS

To start and stop BusinessWare:
! vtadmin start system <BusinessWare Service Name>
Starts BusinessWare through vtadmin.
! vtadmin stop system <BusinessWare Service Name>
Stops the BusinessWare through vtadmin.
Note: If service name contains spaces, enclose it within double quotes.
STARTING AND STOPPING BUSINESSWARE IN UNIX

To start and stop BusinessWare:
! vtadmin start system [<BusinessWare Server Path>]
Starts BusinessWare through vtadmin.
! vtadmin stop system [<BusinessWare Server Path>]
Stops the BusinessWare through vtadmin.
Note: If service name contains spaces, enclose it within double quotes.
Note: If no path is specified, the default server is /Servers/bserv1.
ADMINISTERING BUSINESSWARE AND COMMUNICATOR SERVERS

To administer BusinessWare servers, use the following commands:
! vtadmin check bserv <bserv path> [-fix]

Administering BusinessWare and Communicator Servers
Checks the namespace of the BusinessWare Server at <bserv path>. Running

without this option reports the results. The [-fix] option can help recover from
namespace corruption.
! vtadmin checkall bserv [-fix]
Checks the namespace of all the BusinessWare servers under BWROOT.
Running without this option reports the results. The [-fix] option can help
recover from namespace corruption for all the BusinessWare Servers.
! vtadmin listall bserv [<project path>]
Lists all the BusinessWare servers in the namespace. If <project path> is
given, only the BusinessWare Servers used by that project are listed.
! vtadmin listdependency bserv <bserv path>
Lists all projects that depend on the specified BusinessWare Server.
! vtadmin inspectchannel bserv <bserv path> [-fix]
Checks if the channels in the Communicator server and the directory server
entries are synchronized. The [-fix] option corrects any synchronization
problems.
! vtadmin getProperties bserv <bserv path> [<xml file
path>]
Generates an XML file with properties.
! vtadmin setProperties bserv <xml file path>
Reads the XML file and updates the properties.
To administer Communicator servers, use the following commands:
! vtadmin backup chanserv <Communicator Server path>
<backup file name>
Creates a backup of the Communicator servers data (DAT) file.
! vtadmin stat chanserv <Communicator Server path>
[<report interval> <averaging interval>]
Returns thread utilization for the Communicator server. You can specifiy
either both or only report interval. In that case, averaging interval will be the
default value.
! vtadmin listtransactions chanserv
<Communicator Server path>
Lists all the transactions on the specified server.
! vtadmin finishtransaction chanserv
<Communicator Server path> <xid>
Commits the transaction on the specified Communicator server given the
transaction ID.

! vtadmin rollbacktransaction chanserv

<Communicator Server path> <xid>
Rolls back the transaction on the specified Communicator server given the
transaction ID.
! vtadmin getProperties chanserv
<Communicator Server path> [<xml file path>]
! vtadmin setProperties chanserv <xml file path>
ADMINISTERING PROJECTS
To administer projects, use the following commands:
! vtadmin getinfo project <jar file or path>
Show information about the project in the JAR file or project path.
! vtadmin listall project [<project root path>]
Lists all the projects in the namespace. If <project root path> is provided, list
only project versions under that project root.
! vtadmin stopall project
Stops all the projects in the namespace.
! vtadmin deploy project <jar file> [-overwrite]
[-keepall | -removeall]
[-keepchannels | -removechannels]
[-keepqueues | -removequeues]
[-keepservers | -removeservers]
[-useparams <project info file>]
Deploys the project in the <jar file> to directory server. If the project already
exists, the optional parameters tell what to do with its resources:
" -overwriteIf project exists, overwrites the project in directory server.
" -keepallKeeps channels, queues, and servers of the existing
deployment.
" -removeallRemoves channels, queues, and servers of the existing
deployment.
" -keepchannelsKeeps channels of the existing deployment.
" -removechannelsRemoves channels of the existing deployment.
" -keepqueuesKeeps queues of the existing deployment.
" -removequeuesRemoves queues of the existing deployment.

" -keepserversKeeps Integration Servers of the existing deployment.

" -removeserversRemoves Integration Servers of the existing
deployment.
" -useparamsConfigures a project based on the parameter values.
! vtadmin listdependency project <project path>
Lists all projects dependent on the specified project.
! vtadmin start project <project path> [-stopifrunning]
[-allowPartialStart]
Starts the specified project. Optional parameters:
" -stopifrunningStops the project if it is already running. (This option
is deprecated; you should use the vtadmin restart project
command instead.)
" -allowPartialStartIgnores source connector startup errors and
starts the rest of the project.
! vtadmin check project <project path>
Reports status of the specified project.
! vtadmin stop project <project path>
Stops the specified project.
! vtadmin restart project <project path>
[-allowPartialStart]
Restarts the specified project. The -allowPartialStart option instructs
BusinessWare to ignore any source connector startup errors and start the rest
of the project.
! vtadmin undeploy project <project path>
[-keepall | -removeall]
[-keepservers | -removeservers]
[-keepchannels | -removechannels]
[-keepqueues | -removequeues]
[-ignoredependents]
Undeploys the specified project from directory server. The optional
parameters specify what to do with its resources:
" -keepallKeeps channels, queues, and servers of the existing
deployment.
" -removeallRemoves channels, queues, and servers of the existing
deployment.
" -keepchannelsKeeps channels of the existing deployment.
" -removechannelsRemoves channels of the existing deployment.

" -keepqueuesKeeps queues of the existing deployment.

" -removequeuesRemoves queues of the existing deployment.
" -keepserversKeeps Integration Servers of the existing deployment.
" -removeserversRemoves Integration Servers of the existing
deployment.
" -ignoredependentsIgnores dependent projects and do not ask user.
! vtadmin purge project <project path>
[-all][-channels][-queues][-DOs][-allConnectors]
[-allComponents][-Component <component path>]
[-Connector <connector path>][-dropTables]
Purges the projects components and connectors.
" -allPurges all channels in channel connectors and queues associated
with connectors and deletes all DOs.
" -channelsPurges all channels in channel connectors.
" -queuesPurges all the queues associated with connectors.
" -DOsPurges DOs from all stateful components.
" -allConnectorsPurges states of all connectors.
" -allComponentsPurges BPOs and timers associated with all of the
projects components.
" -Component <component path>Purges BPOs and timers
associated with the specified component.
" -Connector <connector path>Purges states of the specified
components.
" -dropTablesDrops tables from database. Default is to truncate the
tables.
! vtadmin getProperties project <project path>
[<xml file path>]
Generates XML file with properties.
! vtadmin setProperties project <xml file path>
! vtadmin updateschema project <project path> [-file
<filename>]
Compares the projects BPO/DO schema to the schema in the database and
modifies the schema in the database, if necessary. If the optional -file is
specified, no schema change is made in the database, but an SQL script is
generated and saved to the specified file.

! vtadmin generateschema project <project path> -file

<filename>
Generates the SQL commands of the schema and saves them to the specified
file. You would use this command if you want to generate the database schema
of the project without connecting to the database server.
Note: You cannot modify the existing attributes or fields in the schema (such as
changing the name or type of the attribute) when you use the updateschema
and generateschema commands. However, the commands do handle the
following cases:
" Add or remove attributes of an existing BPO/DO.
" Add or remove fields of a struct in an existing BPO/DO.
" Add or remove DOs from the project.
To administer project groups:
! vtadmin start projectgroup <project group path>
Starts the projects in the project group.
! vtadmin stop projectgroup <project group path>
Stops the projects in the project group.
! vtadmin check projectgroup <project group path> [-all]
Checks the status of projects in the project group. Optional parameter:
" -allchecks the status of child project groups.
! vtadmin listall projectgroup [<project group path>]
[-all]
Lists all the projects in a project group or lists all project groups if no project
group is specified.
" -allAlso lists the projects in the child project groups.
! vtadmin info projectgroup <project group path>
Displays the info available for the project group.
ADMINISTERING PROJECT COMPONENTS
WARNING: Changing property values may corrupt your deployed project.

Always back up existing settings using the vtadmin getProperties
command prior to making changes. Restart the server after changing the
properties.

INTEGRATION SERVERS
To administer Integration Servers, use the following commands:
! vtadmin check server <integration server path> |
<channel server path> | <base server path>
Reports the status of specified server. The path can be an Integration Server,
base server, or Communicator Server.
! vtadmin checkall server
Checks and fixes the IORs of all the servers under BWROOT if they are invalid.
Does not refresh IORs for dead proxies related to projects that have been
stopped.
! vtadmin listall server [<project path> | <bserv path>]
The optional path can be a project or a BusinessWare Server. If not specified,
list all Communicator Servers, base servers, and Integration Servers in the
namespace.
" If a project is specified, list only the servers it uses.
" If a BusinessWare Server is specified, list only the servers it uses.
! vtadmin listprojects server <server path>
Lists projects running on the specified server.
! vtadmin start server <integration server path> |
<base server path>
Starts the specified server.
! vtadmin stop server <integration server path> |
<base server path>
Stops the specified server.
! vtadmin startall server [<bserv path>]
Starts all Integration Servers and base servers in the namespace. If the
BusinessWare Server is specified, starts all Integration Servers and base
servers under that server.
! vtadmin stopall server [<bserv path>]
Stops all Integration Servers and base servers in the namespace. If the
BusinessWare Server is specified, stops all Integration Servers and base
servers under that server.
! vtadmin delete server <integration server path>
Deletes the specified Integration Server.
! vtadmin listtransactions server
<integration server path>

Lists all the transactions with the transaction ID and the state of the specified
server.
! vtadmin forceheuristic server <integration server path>
<xid> <commit>/<nocommit>
Forces heuristic outcome on this particular transaction. The transaction ID is
specified along with flag commit if the transaction needs to be committed or
nocommit if it is not desired.
! vtadmin finishtransaction server
<integration server path> [<xid>]
Finishes the transaction on the specified Integration Server given the
transaction ID.
! vtadmin rollbacktransaction server
<integration server path> [<xid>]
Rolls back the transaction on the specified Integration Server given the
transaction ID.
! vtadmin getProperties server <server path> [<xml file
path>] or
vtadmin getProperties server <project name> <server
name> [<xml file path>]
! vtadmin setProperties server <xml file path>
Reads an XML file and updates the properties.
! vtadmin stat server <server path> [<report interval>
<averaging interval> <pool>]
Returns pool utilization for server.
CONNECTORS
To administer connectors, use the following commands:
! vtadmin setPosition connector <project path>
<connector name> <position> or
vtadmin setPosition connector <connector path>
<position>
Sets the Channel Source connector position to the specified integer number in
a fully qualified string input in a format returned by getPosition.
! vtadmin getPosition connector <project path>
<connector name> or

vtadmin getPosition connector <connector path>

Gets the Channel Source connector position.
! vtadmin getProperties connector <project path>
<connector name> [<xml file path>] or
vtadmin getProperties connector <connector path>
[<xml file path>]
! vtadmin setProperties connector <xml file path>
! vtadmin start connector <project path> <connector name>
Starts connector for the project. All instances of connectors across the project
are started.
! vtadmin stop connector <project path> <connector name>
Stops connector for the project. All instances of connectors across the project
are stopped.
CHANNELS AND QUEUES

To administer channels, use the following commands:
! vtadmin check channel <channel path>
Checks status of the channel at <channel path>.
! vtadmin create channel <new path> [Basic | Composite |
Replica | Status] [Reliable | Guaranteed]
[<channel source paths> ...]
Creates a channel at the specified path of the given type. The default type is
Basic Guaranteed. For a replica channel, specify a channel source. For a
composite channel, specify a list of channel sources.
! vtadmin create channel <new path> Shortcut
<target channel path>
Creates a BusinessWare 4.x shortcut in the directory server to an existing
BusinessWare 3.x channel. The target channel format is <vtname>channel,
including the angle brackets; quote the target channel so the angle brackets are
not interpreted as redirects.
! vtadmin delete channel <channel path>
Deletes the specified channel.
! vtadmin listall channel [<project path>]

Lists all channels in the namespace. If <project path> is specified, list only
channels it uses.
! vtadmin listpublishers channel <channel path>
Lists all publishers to the specified channel.
! vtadmin listsubscribers channel <channel path>
Lists all subscribers of the specified channel.
! vtadmin purge channel <channel path> [<low> <high>]
Purges events in the channel specified by <channel path>. If <low> and
<high> are specified, purge only events at positions <low> to <high>
inclusive.
! vtadmin rename channel <channel path> <new path>
Renames a channel from the old path to the new path.
! vtadmin getProperties channel <channel path>
[<xml file path>] or
vtadmin getProperties channel <project path>
<channel name> [<xml file path>]
! vtadmin setProperties channel <xml file path>
To administer queues, use the following commands:
! vtadmin check queue <queue path>
Checks status of the queue at <queue path>.
! vtadmin create queue <new path> [Reliable | Guaranteed]
Creates a queue of the given type at the specified path. The default type is
Guaranteed.
! vtadmin delete queue <queue path>
Deletes the specified queue.
! vtadmin listall queue [<project path>]
Lists all queues in the namespace. If <project path> is specified, list only
queues it uses.
! vtadmin listpublishers queue <queue path>
Lists all publishers to the specified queue.
! vtadmin listsubscribers queue <queue path>
Lists all subscribers of the specified queue.
! vtadmin purge queue <queue path> [<low> <high>]

Administering Clusters
Purges events in the queue specified by <queue path>. If <low> and <high>
are specified, purge only events at positions <low> to <high> inclusive.
! vtadmin rename queue <queue path> <new path>
Renames a queue from the old path to the new path.
! vtadmin replay queue <queue path> [<low> <high>]
Replays consumed events from the queue. If <low> and <high> are specified,
replay only events at positions <low> to <high> inclusive. If <low> and
<high> are not specified, they default to 0 and -1, respectively.
! vtadmin getProperties queue <queue path>
[<xml file path>] or
vtadmin getProperties queue <project path>
<queue path> [<xml file path>]
! vtadmin setProperties queue <xml file path>
ADMINISTERING CLUSTERS
To administer clusters, use the following commands:
! vtadmin check cluster <project path> <cluster name>
Checks status of a cluster in a project.
! vtadmin listall cluster <project path> [<cluster name>]
Lists all the clusters in a project or lists all Integration Servers in a cluster if
the cluster name is specified.
! vtadmin getProperties cluster <project path>
<cluster name> [<xml file path>]
! vtadmin setProperties cluster <xml file path>
LISTING PROXIES
To list all the proxies used by a project:
! vtadmin listall proxy <project path>
Lists all the proxies in the specified project.

Administering Performance Monitoring
ADMINISTERING PERFORMANCE MONITORING

This section describes how to administer BusinessWare performance monitoring.
See also the BusinessWare Performance Guide.
To monitor individual servers, use the following commands:
! vtadmin start monitor server <server path>
Resets to zero and starts the monitor and all the project-level performance
counters in the server.
! vtadmin stop monitor server <server path>
Stops the monitor and all the project-level performance counters in the server.
! vtadmin dump monitor server <server path> <dir path>
Dumps all system and project level counters for that server to a file or files
(one per server) in the specified directory.
The first two commands start/stop all the performance counters in the server. The
third command writes the counter values to a file in XML format.
To monitor individual projects, use the following commands:
! vtadmin start monitor project <project path>
Resets to zero and starts the monitor and application-level and system-level
performance counters for the project across multiple servers if necessary.
! vtadmin stop monitor project <project path>
Stops the monitor and application-level and system-level performance
counters for the project across multiple servers if necessary.
! vtadmin dump monitor project <project path> <dir path>
Dumps performance counters for all system-level counters for that project into
a file in the specified directory.
The first two commands start and stop the performance counters for the project in
all the Integration servers it is using. They also start and stop the system counters,
such as transaction manager, in the servers. The third command writes the counter
values to files in XML format. When the project is running in multiple servers,
this command will create one file per server. The file names will be the <dir
path>_<server name> for server with the name <server name>.
EXAMPLES
The following examples show the essentials of using the vtadmin utility.
Example: Create a Channel:

Examples
> vtadmin create channel /Servers/bserv/myChannel2

>
(A channel named myChannel2 appears in the directory server console.)

Example: Display vtadmin argument help:
> vtadmin help

For help on specific component type, run 'vtadmin help
<Component Type>'.
List of supported component types:
bwConfig
bserv
system
server
channel
queue
project
schema
connector
chanserv
projectgroup
proxy
cluster
monitor
Example: Display vtadmin channel argument help:
> vtadmin help channel

vtadmin [-v -g <trace level> -o <trace spec> -userdn
<userdn> -userpwd <userpwd>] <command> <type>
<parameters>
All paths refer to the directory server path of each item
relative to BWROOT.
For channel type:

check channel <channel path>
Check status of the channel at <channel path>.
create channel <new path>
[Basic | Composite | Replica | Status]
[Reliable | Guaranteed] [channel source path(s)>
...]
Create a channel at the specified path of the given
type.
The default type is Basic Guaranteed.
For a replica channel, specify a channel source.

Examples
For a composite channel, specify a list of channel

sources.
create channel <new path> Shortcut <target channel path>
Create a BW4.x shortcut in directory server to an
existing BW3.x channel. Target channel format is
<vtname>channel, including the angle brackets; quote
the target channel so the angle-brackets are not
interpreted as redirects.
delete channel <channel path>
Delete the specified channel...

4 4 SECURITY AND USER MANAGEMENT
This chapter discusses how BusinessWare provides a framework and facilities for
security and user management. Topics include:
! Overview of Organizational Models
! Security Models in BusinessWare
! Directory Server Basics
! Managing Users and Groups
! Administering Access Control
! Federating BusinessWare 4.x Instances
! Secure Communication Using SSL
OVERVIEW OF ORGANIZATIONAL MODELS

The critical factor in setting up security policies for your application is your
organizational model. An organizational model describes not only the physical
structure of your organization but also how your organization operates in the
business environment.
The basic elements of the organizational model typically include but are not
limited to:
! Users
! Groups
! Roles
! Relationships

SECURITY AND USER MANAGEMENT
Overview of Organizational Models
USERS AND GROUPS

Users and groups are created and managed using your directory server facilities.
(See Directory Server Basics on page 4-3 and Managing Users and Groups on
page 4-10.) A role group refers to a physical group in your directory server that
is used for role mapping purposes only, while an organizational group refers to
a physical group in your directory server that represents an organizational unit.
See Roles.
Deployers should create an individual role group for every role defined in the
application projects and map the role to the corresponding role group. Mapping
two roles to the same role group is strongly discouraged. After project
deployment, administrators can grant/revoke users or groups to/from a role using
the Application Administration Tool, which essentially manipulates the members
of the role groups.
By default, BusinessWare defines two groups: BusinessWare Administrators

and BusinessWare Users, which are examples of role groups. BusinessWare
Administrators are given full permissions under BW_ROOT and have special
privileges to administer BusinessWare components and to access the Web
Administration Tool and Application Administration Tool. BusinessWare
Users represent the collection of the users who interact with some of the
BusinessWare components. BusinessWare Users are also used by some of
BusinessWare samples that involve workflow and may not be ideal for security
control in production.
ROLES
A role is a logical grouping of users that is defined by an application component
provider. A deployer typically maps roles to distinct role groups. Mapping roles
to organizational users and groups is not recommended. See the BusinessWare
Modeling Guide for more information on mapping roles.
RELATIONSHIPS
A relationship forms a named and directional binding that ties one organizational
principal (user or group) to another in the directory server. For example, an
engineering manager has a relationship to a group within the engineering
organization. Relationships are recorded by an attribute (vtrelationshipdef)
in the directory server schema installed by BusinessWare. The objectclass for
relationships is vtrelationships-10 and it is added automatically to the
schema by the API when a relationship is created.

Security Models in BusinessWare
You set up relationships using the Application Administration UI. See the
Application Administration Help for more information. The only currently
defined and supported relationship is BW Manager.
Note: You should create relationships only in organizational groups, not in role
groups.
SECURITY MODELS IN BUSINESSWARE

Security is a complex issue for any enterprise system. BusinessWare implements
the following models to provide a full range of security options.
! AuthenticationBusinessWare uses the LDAP user registry for
authentication of users. All remote invocations into a BusinessWare model are
authenticated. BusinessWare provides a guest credential to be used with
calls from third-party ORBs that do not contain a valid BusinessWare
credential. See Administering Access Control on page 4-16 for more
information.
! Authorizationadministrative rights are implemented in BusinessWare as
LDAP permissions on configured objects. BusinessWare Workflow
implements various rights for Workflow performers and supervisors. See
Administering Access Control on page 4-16 for more information.
! Application Permissionsapplication permissions for synchronous
invocations are implemented as permissions on port objects. See
Administering Access Control on page 4-16 for more information.
! SSL-Based Encryptionby default, BusinessWare runs under TCP/IP. To
use SSL-based encryption in BusinessWare, see Secure Communication
Using SSL on page 4-25.
DIRECTORY SERVER BASICS

LDAP is a standard directory service protocol that provides access control, white
pages services, and a distributed computing directory for large distributed
systems.
Note: See the BusinessWare Installation Guide for your platform to determine
which directory server products BusinessWare currently supports.

Directory Server Basics
IMPORTANT: BusinessWare uses the LDAP directory service for user

directory, namespace and security control. You should use a separate directory
server rather than the corporate directory server for these purposes. You may
need to set up replication of user directories between the corporate directory
server and the directory server for BusinessWare applications.
Essentially, LDAP defines how clients access data on a distributed server. LDAP-
driven access controlwho can see what data and how users are defined to the
systemprovides security for the system, along with naming and directory
services.
LDAP directories store data in Directory Information Trees (DIT), which are
hierarchical data structures. Each node in the tree is called an entry. Entries are
collections of attributes that include DNsstring representations that uniquely
identify users, systems, and organizations. DNs contain both a unique name and a
set of attributes. Table 4-1 shows common LDAP Distinguished Name attributes.
Table 4-1 LDAP Distinguished Name Attributes

Component Name Definition
CN Common Name Identifies the person or object defined by
the entry
UID User ID Identifies the person or object by user ID
mail Mail Identifies the person or object by e-mail
address
OU Organizational Unit Identifies a unit within the organization
O Organization Identifies the organization in which the
entry resides
L Locality Identifies city, county, township, or other
geographic region in which the entry
resides
ST State Identifies the state or province in which the
entry resides
C Country Identifies the name of the country in which
the entry resides
DC Domain Controller Identifies root node in directory
DNs not only uniquely identify a piece of data, but they do so in a way that shows
the relationship of the entry to the rest of the DIT. For example, assume that
Figure 4-1 defines a data tree for your organization.

Figure 4-1
Figure 4-1 Example LDAP Directory Tree
In this case, the DN for pjohnson would be:

uid=pjohnson, ou=people, o=en
In this case, the DN not only identifies pjohnson, but also provides an overall
organizational map that shows how pjohnson fits into larger hierarchical data
structures.
Note: LDAP provides a consistent view of data, but does not provide
transactions or rollback services.
BASIC USE
In general, any LDAP service provides the following basic operations:
! Connect to the directory server
! Bind to the directory server
! Search the server
! Add a new entry
! Modify an entry
! Delete an entry
! Disconnect from the directory server

For instructions on how to complete these tasks with your directory server, see
your product documentation.
Tip: Back up your directory servers regularly to avoid problems restoring them
in the event of a directory server failure.
IMPORTANT: Commands for performing LDAP operations, such as

ldapmodify, can be found in the bin directory of your directory server client
tools installation. Make sure the appropriate bin directory is accessible from
your PATH.
USING THE BUSINESSWARE NAMESPACE

This section provides an overview of the BusinessWare namespace and the
attribute and objectclass types that BusinessWare installs in the directory service.
To best administer a Businessware directory service, you should understand how
the BusinessWare Installer installs schemas, namespaces, users/groups,
containers, entries, and how the BusinessWare project JAR file is deployed. This
section describes how the Installer performs these operations.
Schema Installation
The BusinessWare Installer uses the appropriate schema file (bwschema.xml
for Sun ONE Directory Server, bwschema-ad.xml for Active Directory, and
bwschema-ibmdir.xml for IBM Directory) to install the directory schema.
Once the schema is installed, there will be many new attribute and objectclass
types in the directory service. Many of these attribute and objectclass types carry
the vt (Vitria) prefix. There also may be additional types for Java or CORBA
depending on the directory server you are running.
The object identifiers used for the installed attribute types are of the following
forms:
! 1.3.6.1.4.1.42.2.27.4.1.x for the CORBA and Java types
! 1.3.6.1.4.1.5559.7.1.x for the Vitria vt types
The object identifiers used for the installed objectclass types are of the following
forms:
! 1.3.6.1.4.1.42.2.27.4.2.x for the CORBA and Java types
! 1.3.6.1.4.1.5559.7.2.x for the Vitria vt types.

Note: Object identifiers determine schema type identity. So, if two schema
types have the same human readable name but different object identifiers, they
are different.
Namespace Installation
The Directory Manager account (or installer account for Active Directory) also
installs the namespace. Namespace installation cannot be performed by a
bwadmin account since neither the bwadmin account or BW_ROOT have been
created yet.
After creating the namespace root BW_ROOT, the Installer creates the top-level
containers in the directory. Except for new user and group entries in the directory,
everything that BusinessWare deploys goes in these top-level containers.
BW_ROOT is the top-level container; the other containers are added underneath.
The installer adds BW_ROOT to either the .vtparams file or the VTPARAMS
environment variable.
Typical BW_ROOT definitions include the following:

! CN=BusinessWare,O=fabrikam.com
! CN=BusinessWare,DC=fabrikam,DC=com
(The definitions vary depending on which directory server you have installed.)
The following containers are created under BW_ROOT container:

! CN=Config,%BWROOT% (e.g.,
CN=Config,CN=BusinessWare,DC=fabrikam,DC=com)
! CN=Projects,%BWROOT%
! CN=Servers,%BWROOT%
! CN=Types,%BWROOT%
! CN=bserv1,CN=Servers,%BWROOT%
! CN=4.2,CN=Types,%BWROOT%
Note: This namespace is conceptually associated with the BusinessWare
version or release.
User and Group Creation

The Directory Manager or installer account also creates users and groups. The
initial groups created include the BusinessWare Administrators group and the
BusinessWare Users group. The BusinessWare Administrators group is given
superuser privileges under BWROOT. All BusinessWare Servers run with the user
credential of the BusinessWare Administrator.

Note: BusinessWare Administrators and BusinessWare Users are role

groups, not organizational groups. See Roles on page 4-2.
By default, Sun ONE Directory Server creates containers OU=Groups and
OU=People under each domain. So after installation of Sun ONE Directory
Server, depending on the version, there would be one of the following two sets of
containers:
! OU=Groups,O=fabrikam.com and OU=People,O=fabrikam.com
! OU=Groups,DC=fabrikam,DC=com and
OU=People,DC=fabrikam,DC=com
By default, Active Directory puts both groups and users together in the following
container:
! CN=Users,DC=fabrikam,DC=com
Note: DC=fabrikam,DC=com will be something different for each customer.
Sun ONE Directory Server puts the BusinessWare Administrators group and the
BusinessWare Users group in the Groups container. Active Directory puts both
groups and users in the Users container. By default, there are no existing Users or
Groups containers in IBM Directory. You should create your own containers
similar to the ones described for Sun ONE or Active Directory.
Active Directory BWROOT Privileges

For installations where Active Directory is the directory server, BusinessWare
uses a tool called adtool to set permissions for the BusinessWare Administrators
group. This tool adds an Access Control Entry (ACE) to the Discretionary Access
Control List (DACL) of the BWROOT directory entry.
For more information on the use of the adtool at installation time, see the
BusinessWare Installation Guide.
Server-Specific Containers and Entries

The administrator user creates server-specific containers and entries. Top-level
containers are installed during namespace installation. Those containers are
specific to a particular version or release of BusinessWare. When the Installer
installs a directory server schema, it creates a container for the particular
By default, the name of a BusinessWare Server is the fully-qualified host name of

the machine. If, for example, the name of a BusinessWare Server is:
thor.fabrikam.com

then the default setting for the BSERVDN is:

"CN=thor.fabrikam.com,CN=Servers"
Note: BSERVDN directory name is relative to BWROOT.
When the Installer installs bserv-ad.xml, it then creates the following

container:
CN=thor.fabrikam.com,CN=Servers,CN=BusinessWare,DC=vit
ria,DC=com
In this example, BWROOT is CN=BusinessWare,DC=vitria,DC=com.

Tip: BSERVDN does not have to be set to the default, although it is good practice
to do so.
IMPORTANT: Do not use a BSERVDN setting that requires creating a chain of

containers. If one of the servers in the chain has not yet been created, the
operation will fail.
bserv(-ad).xml DSML specifies the following entries in the BSERVDN

container. Some of these entries are containers themselves.
! CN=admin,%BSERVDN%,%BWROOT%
! CN=WebServer,CN=DefaultServer,CN=admin,%BSERVDN%,
%BWROOT%
! CN=DefaultServer,CN=admin,%BSERVDN%,%BWROOT%
! CN=local,%BSERVDN%,%BWROOT%
! CN=chanserv,CN=local,%BSERVDN%,%BWROOT%
! CN=channels,%BSERVDN%,%BWROOT%
! CN=statsChannel,CN=channels,%BSERVDN%,%BWROOT%
! CN=DeployedProjects,%BSERVDN%,%BWROOT%
SUMMARY OF THE BUSINESSWARE NAMESPACE

The following example shows what a typical installation might look like.
Assume the following defaults:

! BWROOT="CN=BusinessWare,DC=fabrikam,DC=com"
! BSERVDN="CN=thor.fabrikam.com,CN=Servers"

Managing Users and Groups
In this example, the top-level container would look as follows:

! CN=BusinessWare,DC=fabrikam,DC=com
The following containers would be associated with the release installation:

! CN=Config,CN=BusinessWare,DC=fabrikam,DC=com
! CN=Projects,CN=BusinessWare,DC=fabrikam,DC=com
! CN=Servers,CN=BusinessWare,DC=fabrikam,DC=com
! CN=bserv1,CN=Servers,CN=BusinessWare,DC=fabrikam,DC=com
! CN=Types,CN=BusinessWare,DC=fabrikam,DC=com
! CN=4.2,CN=Types,CN=BusinessWare,DC=fabrikam,DC=com
The installation would contain the following BusinessWare Server entries:

! CN=thor.fabrikam.com,CN=Servers,CN=BusinessWare,DC=fabr
ikam,DC=com
! CN=admin,CN=thor.fabrikam.com,CN=Servers,CN=BusinessWar
e,DC=fabrikam,DC=com
! CN=WebServer,CN=DefaultServer,CN=admin,CN=thor.fabrikam
.com,CN=Servers,CN=BusinessWare,DC=fabrikam,DC=com
! CN=DefaultServer,CN=admin,CN=thor.fabrikam.com,CN=Serve
rs,CN=BusinessWare,DC=fabrikam,DC=com
! CN=local,CN=thor.fabrikam.com,CN=Servers,CN=BusinessWar
e,DC=fabrikam,DC=com
! CN=chanserv,CN=local,CN=thor.fabrikam.com,CN=Servers,
CN=BusinessWare,DC=fabrikam,DC=com
! CN=channels,CN=thor.fabrikam.com,CN=Servers,CN=Business
Ware,DC=fabrikam,DC=com
! CN=statsChannel,CN=channels,CN=thor.fabrikam.com,CN=Ser
vers,CN=BusinessWare,DC=fabrikam,DC=com
! CN=DeployedProjects,CN=thor.fabrikam.com,CN=Servers
CN=BusinessWare,DC=fabrikam,DC=com
MANAGING USERS AND GROUPS

For each person that you want to be able to interact with BusinessWare
components, such as ports, channels, queues, and process views, you must do the
following:

1. Create a user in your directory server to represent the person to the system.
2. Add the user to the appropriate role groups either directly or, even better,
indirectly via organizational groups.
3. Give the role group access rights to those components you want to let the users
in the role group work with.
All the users and groups in BusinessWare use the special object classes (or
schemas), vtuser-11 and vtgroup-10, with BusinessWare-specific attributes
in addition to those defined by the directory server vendors. You must add the
corresponding object class to the existing users and groups who will be accessing
BusinessWare resources and components.
Note: You can use the Application Administration UI to convert non-
BusinessWare users to BusinessWare users. See the Application Administration
Help for more information.
IMPORTANT: For easy administration, you should grant permissions or access

rights to the role groups instead of users. Therefore, removing a user from a role
groups requires no changes to your security setting. If you set security with users,
you must also remove that deleted user from all the groups that the user belongs
to or the groups that contain invalid users are no longer usable. Likewise, if you
delete a user from the BusinessWare Users group under the Group node in the
directory server and delete the user from the People node under the Vitria root
node, you must also delete the user from the BusinessWare Users node.
ROLE GROUPS, RIGHTS, AND ACCESS LEVELS

BusinessWare users can work only with BusinessWare resourcesfolders,
projects, channels, models, and so forthto which they have been given access.
You should set security with role groups (rather than individual users or
organizational groups). Access to an objecta folder, saygives members of a
role group rights to work with it in certain ways. For example, a role group may
be given the right to use the objects in a folder but not the right to change those
objects. Giving a role group access rights on an object is also called setting
permissions.
The rights role groups have to a particular resource depend on the level of access
they have been given to that resource. The system defines access levels by
collecting types of rights into the groupings you are most likely to want to give
role groups. You can also give role groups ad hoc access level groupings.

CREATING GROUPS AND USERS USING SUN ONE DIRECTORY

SERVER
You create group and user objects in Sun ONE Directory Server using the native
Sun ONE Directory Server GUI. See your Sun ONE Directory Server
documentation for more information.
Groups
The attributes for a group are:
! dndistinguished name (a unique name and set of attributes)
! vtgidunique group ID (The group ID should reflect the purpose or use of
the group.)
! cncommon name
! objectclassgroup schema
! descriptiondescription of object
! vtmailemail address
! vtworklisthandlerfull name of the associated Task Manager project
(This attribute should be set only if the group is used as a role group.)
! vtrelationshipdefname of the relationship and the target object of the
relationship
! uniquemembermembers of group
The following is an example of a representation of a group object in Sun ONE

Directory Server:
dn: cn=apps group,ou=groups,o=corp.com

vtgid: apps
cn: apps group
objectclass: top
objectclass: groupOfUniqueNames
objectclass: vtgroup-10
description: This is the apps group
vtmail: apps@corp.com
vtworklisthandler: /Projects/TaskManager/initial
vtrelationshipsdef: BW Manager:: uid=dsanders, ou=people,
dc=corp.com
uniquemember: uid=rjackson,ou=people, o=corp.com;
uid=ajones, ou=people, o=corp.com;
uid=ysmith, ou=people, o=corp.com;....

Users
The attributes for a user are:
! uiduser ID
! cncommon name
! snsurname
! vtprincipaluser principal
! objectclassobject schema
! mailemail address
(This attribute should not be set for users.)
relationship
The following is an example of a representation of a user object in Sun ONE

Directory Server:
dn: uid=ysmith,ou=people,o=corp.com
objectclass: top
objectclass: person
objectclass: inetOrgPerson
objectclass: vtuser-11
cn: Ying Smith
sn: Smith
vtprincipal: username:ysmith
vtmail: ysmith@corp.com
vtrelationshipdef: BW Manager:: uid=dsanders, ou=people,
dc=corp.com
description: This is a user.
The above example is based on the assumption that you start out with an empty
directory. However, there are many cases in which you could have a directory
server already installed in your Corporate Directory Server (CDS). Depending on
your control policy, you may or may not be able to change the schema. If it is
impossible to change the schema of the existing user/group class, you need to have
another directory server replicate the needed attributes from your CDS and extend
the schema to support other BusinessWare-specific attributes.

CREATING GROUPS AND USERS USING ACTIVE DIRECTORY

While the Sun ONE Directory Server GUI supports the extension of the GUI
automatically, Active Directory needs a COM Property Page installed to view/edit
the user-defined attributes. See your Active Directory documentation for more
information.
The mapping of Vitria users/groups to Active Directory is different from Sun

ONE Directory Server. The organization is referred to in Active Directory as
Domain Component (DC). The Active Directory schema is extended to include
the following attributes for groups and users.
Groups
The attributes for a group are:
! SAMAccountNameunique group ID
! cncommon name
! mailemail address
(This attribute should be set only if the group is used as a role group.)
relationship
! membermembers of group
The following is an example of a representation of a group object in Active

Directory:
dn: cn=apps group,cn=groups,dc=corp, dc=com

SAMAccountName: apps
cn: apps group
objectclass: top
objectclass: group
description: This is the apps group
mail: apps@corp.com
vtworklisthandler: /Projects/TaskManager/initial
dc=corp.com
member: cn=ron jackson,cn=users, dc=corp, dc=com;

cn=ann jones, cn=users, dc=corp, dc=com;

cn=ying smith, cn=users, dc=corp, dc=com;....
Users
The attributes for a user are:
! SAMAccountNameunique user ID
! userpassworduser password
! cncommon name
! snsurname
! vtprincipaluser principal
! mailemail address
(This attribute should not be set for users.)
relationship
The following is an example of a representation of a user object in Active

Directory:
dn: cn=ying smith,cn=users,dc=corp, dc=com

objectclass: top
objectclass: person
objectclass: organizationlPerson
cn: Ying Smith
sn: Smith
vtprincipal: username:ysmith
userpassword:********
mail: ysmith@corp.com
dc=corp.com
description: This is a user.

Administering Access Control
As with Sun ONE Directory Server, the above example is based on the assumption
that you start out with an empty directory. However, there are many cases in
which you could have a directory server already installed in your Corporate
Directory Server (CDS). Depending on your control policy, you may or may not
be able to change the schema. If it is impossible to change the schema of the
existing user/group class, you need to have another directory server replicate the
needed attributes from your CDS and extend the schema to support other
BusinessWare-specific attributes.
The user and the group object is modified to extend the vtuser-11 and
vtgroup-10 group objects. Whenever a user or a group is created, the Vitria
properties, such as vtworklisthandler and vtprincipal, can be set up.
(The vtrelationships-10 is added by the API only when a relationship is
created.) Although the attribute vtworklisthandler allows you to associate a
dedicated Task Manager with a role group, you should consider a clustering Task
Manager for better performance and scalability first.
CREATING GROUPS AND USERS USING IBM DIRECTORY

You create group and user objects in IBM Directory, using the appropriate native
directory tools. See your directory server documentation for more information.
The objects are nearly identical to those for Sun ONE Directory Server. See
Creating Groups and Users Using Sun ONE Directory Server on page 4-12.
ADMINISTERING ACCESS CONTROL

BusinessWares security and access control are built on top of the directory
servers native permission controls of READ and WRITE. Several basic types of
components in BusinessWare are subject to the permission control:
! BusinessWare Server
! Communicator Server
! Integration Servers
! Channels
! Queues
! Projects
! Process Views

! Ports
Table 4-2 Directory Server Generic Permissions for BusinessWare Components
BusinessWare Directory Server Generic Permissions
Components
READ WRITE Permission on Entry
Permission on
WRITE Permission on vtPermission-
Entry
Admin
BServ Browse Change Static Attrs Start/Stop Serv
Base/Integration Server Browse Change Static Attrs Start/Stop Serv
Communicator Server Browse Change Static Attrs Create Channel/Queue, Stop Serv, Change
Runtime Attributes
Channel Browse, Subscribe Publish, Purge Destroy Channel; Change Runtime Attributes
Queue Browse Attributes, Publish, Purge, Destroy Queue; Change Runtime Attributes
Browse Events Consume Events
Project Browse Change Settings Deploy/Undepoly/Redeploy, Start/Stop
Project
Process Views Browse Change Settings N/A
Port Browse Deploy, Execute N/A
methods on the Port
The permission should be inclusive of right side in the Table 4-2. Checking
WRITE permission on entry should also implicitly check READ permission
on entry and WRITE permission on vtPermission-Admin should also check
the other two permissions.
Before deploying projects to a directory server, vtadmin and the BME need to
check the ADMIN permission (i.e., WRITE permission on vtPermission-
Admin).
This scheme provides simplicity for novice users and finer control for advanced
users:
! A novice BusinessWare user can set READ and WRITE permissions directly
on the entire entry to achieve the access control listed above. The READ
permission lets the user browse and subscribe. The WRITE permission grants
the user all other write and administration rights, such as deploying
projects, changing attributes, starting and stopping servers.
! Advanced users can get finer control of the ADMIN permission, by revoking
the WRITE permission on the vtPermission-Admin attribute so that the user
will not be able to administer the BusinessWare components (starting,
stopping, etc.).

The READ and WRITE permissions here are in generic terms, which may be
mapped to a group rights for specific directory servers. Assign these groups of
rights together when granting READ or WRITE permission. The following table
lists the LDAP native permissions for each of supported directory server.
Table 4-3 Generic Permissions for Supported Directory Servers

Directory Server Directory Server Generic Permissions
READ WRITE
Sun ONE Directory Read, Search, Compare Write, Selfwrite, Add,
Server Permission Delete
MS ActiveDirectory Read Write
Permission
IBM Directory Server Read Write
Permission
You need to set permissions using the native GUI, which comes with the directory
server. There is no BusinessWare GUI to support this functionality.
The BusinessWare Server credential (from VTPARAMS on the server machine)

must be granted full permissions (READ, WRITE, ADMIN). To deploy a project
to the directory server and the Communicator Server, the user must be granted full
permissions (READ, WRITE, ADMIN).
Table 4-4 BusinessWare Permissions Mapped from Supported Directory Servers

BusinessWare READ (BROWSE) WRITE ADMIN
Permissions
Mapped Sun ONE Read, Search, Compare Read, Search, Compare, Read, Search, Compare,
Directory Server Natives Write, Selfwrite, Add, Write, Selfwrite, Add,
Permissions Delete Delete, Write on
vtPermision-Admin
Mapped ActiveDirectory Read Read, Write Read, Write, Write on
Native Permissions vtPermission-Admin
Mapped IBM Directory Read Read, Write Read, Write, Write on
Server Native Permissions vtPermission-Admin

CACHING PERMISSIONS
Checking permissions against the directory server can be a very expensive
operation. To achieve higher performance, some of the BusinessWare Servers,
such as Communicator Servers and Integration Servers, cache permissions.
Therefore, there may be a delay before a change to the native directory access
control takes effect. The VTPARAM ldap_cache_timeout can be used to
configure the number of seconds BusinessWare components will cache LDAP
access control information. By default, BusinessWare servers will cache this
information for 2 to 5 minutes. Increasing this interval will reduce the load on the
LDAP server but increase the time it takes to revoke privileges.
REQUIRED PERMISSIONS FOR BUSINESSWARE COMPONENTS

This section describes how to set up the required permissions for various
BusinessWare components.
Setting Up Projects With Activity States

In addition to the TaskManager project, workflow application projects (i.e.,
projects that contain activity states) need to be set up with proper permissions. The
project node in the directory server should be assigned read/write permissions for
all the performers specified in the activity states. For example, if the project name
is MyProject, the MyProject item in the directory server should be configured
with these permissions.
Because these permissions are overwritten every time this project is deployed, you
may add these permissions to the top-level entry in the directory server for all
projects. This entry would be the Projects item in the directory, under which all
the projects are deployed.
BUSINESSWARE DEFAULT SECURITY SETTINGS

The BusinessWare Installer automatically sets default access controls so that
BusinessWare Servers and samples can run without any user involvement with
security setting.
The BusinessWare Installer creates two BusinessWare-related role groups at the

common group location in the directory server:
! BusinessWare Administrators
! BusinessWare Users

The BusinessWare Installer grants Full Permissions for these two role groups
for the BW_ROOT subtree where all the BusinessWare data reside. The Installer
also automatically creates a user (the default name is bwadmin), if it does not
exist, and adds the user to the BusinessWare Administrators role group. This
user is the same as the one specified in the VTPARAMS file for the BusinessWare
Servers and the BME.
The BusinessWare Servers must run as members of BusinessWare
Administrators because BusinessWare Servers need full permissions for the
directory entries under BW_ROOT. Deploying BusinessWare projects to the
directory server operates the same way.
In addition, the role of BusinessWare User Administrator is mapped to the

BusinessWare Administrators role group. This mapping is recorded in the
VTPARAMS file, and can be changed at a later time:
bw_user_administrator=<dn>
The BusinessWare Users role group is used primarily for BusinessWare

samples where the samples setup program adds the necessary users to this group
for the sample to run. If you are no longer testing samples, you should remove all
the members in the group to eliminate a potential security breach.
The following is the directory namespace outline for the Sun ONE directory
server after BusinessWare installation:
+
+---People
| +---bwadmin
+---Groups
| +---BusinessWare Administrators [bwadmin as a member]
| +---BusinessWare Users
|
+---<BW_ROOT> [ACI: Full: BusinessWare Administrators]
[ACI: Full: BusinessWare Users]
|
+---Servers
| +---bserv1
+---Projects
| +---BusinessWare
| +---4.2
+---Types
| +------ 4.2
+---Config

SETTING UP A GUEST CREDENTIAL

All remote invocations into a BusinessWare model are authenticated. Since calls
from third-party ORBs do not contain a valid BusinessWare credential, the guest
credential will be used. Before a BusinessWare model can receive invocations
from a client using a third-party ORB, the BusinessWare guest credential must be
configured using Web Administration Tool.
To set up the guest credential:
1. Log into the Web Administration Tool using your directory server user name
and password. The BusinessWare installer created the default user called
bwadmin with a password you provided during the install. You can use this
user, or any other administrative user that you might have created.
2. Click Login.
3. Select the BW Config button to bring up the BusinessWare Configuration
dialog.
4. Enter the guest user ID and guest password (which must be entered twice). The
guest user ID must be the user ID (uid) of a valid BusinessWare directory
server user.
Note: For the directory server, a valid directory server user must have
the vtuser-11 object class.
You can use the BusinessWare Administrator and password listed in
VTPARAMS (e.g., uid=bwadmin,ou=People,dc=vitria,dc=com).
Invocations from foreign systems will assume this credential when they make
calls on BusinessWare.
Note: Do not confuse the guest password with the BusinessWare 3.x
password, which also is specified in this dialog. The BusinessWare 3.x
password is used for interoperability with BusinessWare 3.x as described
in Chapter 8, Interoperability with BusinessWare 3.x Installations.
5. Click OK when you are through.
Note: The guest user ID is only used if the incoming request does not carry a
user/password. This is always true for RMI requests. However, it is possible to
carry a user/password in an HTTP or Web services request. If that is the case,
normal authentication is used. That is, the container looks for a user/password in
an incoming request. If found, it does normal authentication. If not, it treats the
incoming request as guest.

CUSTOMIZING BUSINESSWARE SECURITY AND ACCESS CONTROL

Advanced users may want to customize or fine-tune the access control settings,
based on the BusinessWare security model described above. Since the setting of
access control is done through the directory servers native console, you should
get familiar with the directory server in use, especially with its security policy and
access control.
Note: Your directory server documentation may also include tips on how to
improve performance and reliability of your system.
Adding BusinessWare Administrators

Since a BusinessWare administrator is required to run, administer (start, stop)
BusinessWare Servers, and deploy BW projects, you may want to add additional
administrators for those purposes.
Since the BusinessWare Installer creates a BusinessWare Administrators role

group automatically, which has full permission on BusinessWare data, it is fairly
easy to add another BusinessWare administrator:
1. Add the new user, if necessary.
2. Locate the BusinessWare Administrators group. For Sun ONE, by default,
it is at cn=BusinessWare Administrators, ou=Group, dc=...,dc=...
3. Open the above group, search and add the user of from step 1 as its member.
4. Change the auth_user and auth_password in the VTPARAMS file to match
the user in step 1. To encrypt the password, change it using
bin/platform/hidepwd.
Hints
! Different directory servers may interpret users without a password differently,
which may cause unexpected permission issues and a potential security breach
when running BusinessWare. Therefore, it is safer always to assign a non-
empty password to a user (i.e., do not leave the password field empty).
! In step 3 for an Sun ONE directory server, make sure the users full DN is
specified. Simply typing in the user name is not sufficient. Use the search
feature to get the full DN.

BEST PRACTICES FOR SETTING ACCESS CONTROL

Although there is no single industry standard for LDAP server security, most of
the following best practices apply to all LDAP servers BusinessWare supports.
! You should set security for role groups only, not for individual users and
organizational groups.
! Setting security in BusinessWare is mainly for production systems at the
administering stage.
Setting and managing complex security should be done by LDAP
administrators and BusinessWare administrators (the latter are limited to
BusinessWare-related components) as ongoing activities.
! You should set security for role groups only, not for individual users.
! Think through the whole picture and have a security plan in place before
deploying ACLs.
BusinessWare administrators should develop an overall security plan by
applying as many best practices listed below as possible and avoiding
randomly setting ACLs that may cause future problems in managing these
security settings.
! Minimize the number of ACLs in your directory.
This is the number one rule for setting ACLs in a directory server. The number
of ACLs impacts the directory server performance and manageability.
! Place your ACLs at the highest level in the directory tree structure as possible.
LDAP defines a hierarchical tree structure. By default, the ACLs set on a
parent entry effectively apply to all entries below in the subtree. BW_ROOT,
cn=Servers, and cn=Projects under BW_ROOT are good places to set
ACLs for BusinessWare. But be cautious on setting ACLs at the directory base
entry (for example, dc=Vitria, dc=com), which is the top of the tree and
has too broad, unintended effects.
! Group your ACLs as closely together as possible within your directory.
It is much easier to administer related ACLs if they are not scattered all around
in the directory server. Sun ONE Directory Server supports setting the ACLs
with filters on targeted DNs (for example, cn=proj1*,cn=Projects,...)
and this allows the group fine-grained ACLs at higher level entries, such as
BW_ROOT. This also allows you to preserve ACLs after undeploying projects.
For directory servers that do not support such filters in their ACLs, the fine-
grained ACLs must be set at the entries themselves.
! Set ACLs for role groups, rather than for individual users or organizational
groups.

Federating BusinessWare 4.x Instances
Setting ACLs is relatively more complex than adding users to a specific group.
It is better to create groups (you may consider them roles) and set ACLs
against these groups, not individual users. In this way, ACLs in the directory
do not need to change frequently. Administrators can easily add or remove
users from a specific group/role. The out-of-the-box BusinessWare
Administrators and BusinessWare Users groups are good examples.
! Script the access control settings.
For production systems, you should use scripts to set all ACLs, instead of
using the directory server consoles manually.
FEDERATING BUSINESSWARE 4.X INSTANCES

In BusinessWare 3.x, each BusinessWare Server had its own namespace. Access
to objects on another BusinessWare Servers required federation through shortcuts.
For the most part, this kind of federation is unnecessary in BusinessWare 4.x since
all BusinessWare Servers are typically in a single LDAP namespace. In some
cases, however, you may want to exchange data between BusinessWare instances
running on different directory servers. Many directory servers (such as Sun ONE)
support LDAP referrals, a shortcut-like mechanism native to LDAP. Referrals
allow you to publish/subscribe to channels/queues hosted by BusinessWare
instances that are running on a different directory server.
The following instructions show you how to set up federation between two
BusinessWare instances (BW_instance_1 and BW_instance_2) using different
directory servers (ldap1 and ldap2):
1. Create a channel/queue on BW_instance_2 and create an LDAP referral to the
channel/queue in the namespace of BW_instance_1. To avoid confusion, the
referral should have the same common name as the target object. Also, the
current LDAP user on the local LDAP server must exist (with the same
password) on the remote LDAP server and have adequate access rights.
For example, the following entry on ldap1 links to a channel on ldap2:
ldap://ldap1.vitria.com:389/cn=myChannel,cn=myFolde
r,cn=bserv1,cn=Servers,dc=vitria,dc=com
objectclass = referral
ref =
"ldap://ldap2.vitria.com:389/cn=myChannel,cn=bserv1
,cn=Servers,dc=vitria,dc=com"
Once the channel and referral are created, you should be able to check the
channel/queue on BW_instance_1 with vtadmin using the local name:

Secure Communication Using SSL
vtadmin check channel

/Servers/bserv1/myFolder/myChannel
or using the remote name:
vtadmin check channel
"ldap://ldap2.vitria.com:389/cn=myChannel,cn=bserv1
,cn=Servers,dc=vitria,dc=com"
You can also view it with the channel/queue inspector. Note that the inspector
Browse dialog displays the remote URL of the channel/queue (that is, you
open com, then vitria, then Servers, ...). This makes it clear that the
channel/queue is not on the local directory server.
2. In a project on BW_instance_1, create a folder myFolder and under it a
channel resource myChannel. Partition myFolder/myChannel to be on
/Servers/bserv1. During deployment, you get a warning that
/Servers/bserv1/myFolder/myChannel already exists (the actual
channel is on BW_instance_2).
3. In the project on BW_instance_1 containing myFolder/myChannel, you
can use the channel source/target connectors to subscribe/publish to the
remote channel on BW_instance_2.
The queue source/target connectors can access remote queues on BW_instance_2

in the same way.
Note: The original (local) entry and referred (remote) entry must have the same
relative DN. Also, a local entry and referral entry with the same name should not
exist on the same directory server.
SECURE COMMUNICATION USING SSL

By default, BusinessWare runs under TCP/IP. This section describes how to
configure SSL-based encryption in BusinessWare.
TERMINOLOGY
The following terms are frequently used when discussing authentication, privacy,
and integrity issues with SSL-based encryption:
! PrincipalSecure systems must know precisely who the participants are in
their communications. A participants identity is called a principal. A
Principal can be a user, a client, a server, or an organizational role. In many
systems, every login name is a principal name and vice versa, but this is not
always the case.

! CredentialThe name of a principal is called a credential. BusinessWare

provides built-in mechanisms for determining credentials in any client-server
interaction (authentication). Servers need to know the credential of a client to
determine whether the client is permitted to perform the action it is requesting.
Clients need to know the credential of a server to verify that it is sending
requests and information to the right place.
! Certificates and Certificate AuthoritiesA certificate is a data structure
that fully describes a principal, including the principals credential, an
expiration date, and so on. A certificate authority (CA) issues certificates that
include a code, called a signature, which proves the certificates integrity and
authenticity. By checking the signature, BusinessWare can verify that the CA
actually issued the certificate, and that the certificate is unmodified.
! EncryptionEncryption is the means of providing privacy that takes a
message and changes it into an unreadable format. Once a message is
encrypted, a third party cannot understand it.
Note: A determined third party could try to decode the message, but this
is difficult with modern encryption techniques; with some techniques, it is
virtually impossible.
! Encryption KeysSome encryption techniques use one key, and some use
two keys.
" Symmetric encryption uses the same key, called a secret key, to scramble
and unscramble a message. To use symmetrical encryption, the sender and
receiver must agree on a key.
" Asymmetric encryption, or public key, uses two keys:
# Public key that everyone can know
# Corresponding private key that only the message recipient should
know.
When sending a message, the sender typically encrypts the message using the
recipients public key, and the recipient decodes the message using his private
key. Conversely, a sender could encode data using his own private key, and
the receiver could decode it using the senders public key. This is not the way
to send a private message to a recipient, but it is a way to prove that a particular
message was really sent by a particular entitya digital signature.
IMPORTANT: A private key must be carefully guarded because it

establishes the identity of a principal. In other words, you have your digital
identity because you hold your private key. If someone stole your private key,
that person could pretend to be you and, for example, send out messages
signed by you with your digital signature; no one could tell the difference.

! Connection HandshakeTo establish a secure connection, processes send

and receive messages. This message exchange is called a connection
handshake. Although both participants send and receive messages during the
handshake, the messages are typically not visible to the applications
themselves. During a handshake, the participants:
" Agree on what encryption algorithm to use, if encryption is desired
" Agree on a secret key, if encryption is desired
! Hardened ConnectionsIf a system achieves the three properties of Privacy,
Integrity, and Authenticationthe connection is said to be hardened. Data
sent over a hardened connection is received in the intended way by the
intended receiver only.
SECURITY OPTIONS
The specifics of hardening a connection depend on which security technology you
chose. BusinessWare supports two options:
! Raw TCPno handshake and no security, used only for TCP/IP
communication (default)
! SSLtypically a full handshake and high security
Raw TCP
TCP is the weakest form of security supported by BusinessWare because there is
no encryption or integrity checksum. You must use TCP security when
communicating with other ORBs because the IIOP standard has no provision for
connection handshakes.
When you use TCP security, BusinessWare typically reports the TCP/IP address
at the other end of the connection, as given by the TCP/IP protocol when asked
for a TCP credential. The exception is when an ORB follows the IIOP requirement
that messages from a client contain the clients DN. In this case, the ORB reports
a credential using the clients DN instead of its TCP/IP address. For example, if a
server asks for the credential of a client, the result might be full:DN, where DN
is the clients Distinguished Name. This lets a server perform access control based
on DN.
In other cases, when the ORB does not have access to a DN, it reports the TCP/IP
address of the other end of the connection. For example, if a client asks for the
credential of a server, the result might be tcp:7000@10.206.130.33. This
indicates that no DN is available and the server is running at port 7000 at IP
address 10.206.130.33.

SSL
SSL can make communication between applications and servers arbitrarily
secure. Understanding how BusinessWare uses SSL to provide Privacy, Integrity,
and Authentication, and their performance implications helps you decide which of
the SSL Security Levels is right for your BusinessWare solution.
Privacy
Encryption ensures the privacy of exchanged messages, but its cost makes
communication substantially more expensive. Encrypted communication is up to
ten times slower than unencrypted communication, because absolutely all data is
encrypted, even message headers. Encrypting all data gives an intruder no access
to information, no matter how unimportant that information appears to be.
Anything less than total encryption exposes the system to a variety of subtle
attacks.
Integrity
Integrity means that messages are transmitted correctly and in order. Integrity
enables the receiver to detect any attempt to tamper with the messages, reorder
them, or resend old ones. BusinessWare implements integrity by putting a
sequence number and appending a cryptographically secure checksum to each
block of data. SSL provides integrity as part of the protocol.
Authentication
BusinessWare uses LDAP for authentication and Access Control Lists (ACL).
Because authentication is done at this level, all messages on a given TCP
connection share the same authentication state. This design concept is consistent
with SSL and Kerberos; most high-security systems follow this principle.
When processes establish a secure connection, the transport layer performs a

connection handshake. Because participants perform the handshake when they
establish a secure connection, the performance cost is minimized when
connections are reused.
SSL Security Levels

SSL is a framework for a suite of security protocols or ciphers. These ciphers span
the range from completely unsecure to very secure.
During the connection handshake, a client and server negotiate which cipher they
will use.

IMPORTANT: Do not assume that you have strong security simply because you
are using SSL. You must also choose the right cipher.
Table 4-5 shows the ciphers that BusinessWare supports. These ciphers are not
under United States export control or patent protection.
Table 4-5 Supported SSL Ciphers

Name of Cipher Key Authenti- Encryp- Message Export-
Exchange cation tion Authenti- able
Algorithm Algorithm Algorithm cation (Outside
Code US)
EDH-DSS-RC4-SHA DH DSS RC4(128) SHA1
NULL-SHA RSA RSA None SHA1
NULL-MD5 RSA RSA None MD5
EDH-RSA-DES-CBC3-SHA DH RSA 3DES(168) SHA1
EDH-DSS-DES-CBC3-SHA DH DSS 3DES(168) SHA1
DES-CBC3-SHA RSA RSA 3DES(168) SHA1
RC4-SHA RSA RSA RC4(128) SHA1
RC4-MD5 RSA RSA RC4(128) MD5
EDH-RSA-DES-CBC-SHA DH RSA DES(56) SHA1
EDH-DSS-DES-CBC-SHA DH DSS DES(56) SHA1
DES-CBC-SHA RSA RSA DES(56) SHA1
EXP-EDH-DSS-DES-56-SHA DSA(1024) DSS DES(56) SHA1 yes
EXP-EDH-DSS-RC4-56-SHA DSA(1024) DSS RC4(56) SHA1 yes
EXP-DES-56-SHA RSA(1024) RSA DES(56) SHA1 yes
EXP-RC4-56-SHA RSA(1024) RSA RC4(56) SHA1 yes
EXP-EDH-RSA-DES-CBC-SHA DSA(512) RSA DES(40) SHA1 yes
EXP-EDH-DSS-DES-CBC-SHA DSA(512) DSS DES(40) SHA1 yes
EXP-DES-CBC-SHA RSA(512) RSA DES(40) SHA1 yes
EXP-RC2-CBC-MD5 RSA(512) RSA RC2(40) MD5 yes
EXP-RC4-MD5 RSA(512) RSA RC4(40) MD5 yes
Note: Export regulations are changing as are patent issues. The list of available
ciphers may change at some later date as may the names of ciphers.

CONFIGURING BUSINESSWARE FOR SSL

Most users first install BusinessWare with TCP security, then consider changing
to SSL security when they are ready to deploy the BusinessWare systems that they
have built. For information on installing BusinessWare for SSL using the
Installer, see the BusinessWare Installation Guide for your platform. This section
describes how to configure BusinessWare for SSL using vtadmin or the Web
Admin tool.
IMPORTANT: Even if you set up BusinessWare for SSL, RMI clients and
servers still communicate using TCP/IP.
IMPORTANT: When configured for SSL, BusinessWare does not interoperate

with third-party ORBs.
Setting Up Your Certificate Files

The BusinessWare Server uses the ssl_certificate, ssl_privatekey,
and ssl_capath parameters from the VTPARAMS file when it starts in SSL
mode. Make sure these parameters are set to the appropriate locations and that
those locations contain the appropriate files. See Appendix A, Environment
Variables, Registry Items, and System Files, for more information on the
VTPARAMS file and its parameters.
IMPORTANT: The ssl_certificate, ssl_privatekey, and

ssl_capath variables in VTPARAMS are shared across the directory server and
all BusinessWare Server instances that run on the same machine. Note that you
may also use the ssl_passphrase variable, but you only need it if your
private key is password encrypted.
Note: To obtain a Server Certificate, you must first generate a private key and
Certificate Signing Request (CSR) pair using utilities such as those available
through OpenSSL. Once the CSR is generated, it must be submitted to a CA to be
signed. Different CAs have different procedures to do this; however, the end
result should be a signed certificate for the Server and CA certificate.

Setting BusinessWare to SSL Mode Using vtadmin

To set BusinessWare to SSL mode using vtadmin, run the following command:
vtadmin update BWConfig -security ssl3:
If you want to specify ciphers, use ssl3:<cipher>:<cipher>:... and so on.

For example:
vtadmin update BWConfig -security ssl3:EDH-DSS-RC4-
SHA:NULL-SHA
If you specify one or more ciphers, specify them in priority order. The server uses
the first cipher that it has in common with its client. If there is no common cipher
available, communication fails with an error message.
If you do not select a cipher, the participants choose the most secure cipher that
they both have available. Currently the most secure cipher that BusinessWare
Servers have available is DH_DSS_EXPORT_WITH_DES40_CBC_SHA, but it is
not guaranteed that this will be the cipher that the participants share.
Do not change the value of the encryption string unless you are sure that you want
a specific cipher. Its default value, ssl3:, enables BusinessWare and
Communicator to negotiate which cipher to use on a client-by-client basis.
IMPORTANT: You should not use the NULL cipher because it turns off all
security.
Setting BusinessWare to SSL Mode Using Web Admin

To set BusinessWare to SSL mode using the Web Admin tool, click on the
BWConfig button. Select SSL3 in the security field.
Note: BusinessWare will use the ciphers specified using vtadmin as described
above or the Installer (see the BusinessWare Installation Guide). If no cipher has
been specified, the default cipher (ssl3:) will be used.
Restart the BusinessWare Server
Stop and restart the BusinessWare Server using vtadmin or the Web Admin tool
and then check your credential using the following procedure.
Tip: To ensure that the BusinessWare is running in SSL mode, you should
examine the bserv and chanserv logs in $VITRIA/logs directory.

Client Configuration
Each BusinessWare client program needs to do the following to communicate
with BusinessWare using SSL:
1. Obtain the CA certificate and save it in a directory on its machine.
2. Set the ssl_capath parameter in VTPARAMS to point to the CA certificate.
IMPORTANT: The BusinessWare Server uses the ssl_certificate,

ssl_privatekey and ssl_capath parameters from the VTPARAMS file
when it starts in SSL mode. In a production environment, BusinessWare client
projects should not use the same VTPARAMS file and thus the same certificate
information as the BusinessWare Server. However, client projects will need to
use the same ssl_capath in their VTPARAMS file as the BusinessWare Server
to communicate with the BusinessWare Server in SSL mode.
Note: Authentication of HTTP clients is done through userid/password rather

than through client certificates.
CONFIGURING YOUR DIRECTORY SERVER TO RUN UNDER SSL

It is possible to configure BusinessWare to communicate with the directory server
using LDAP over SSL (sometimes known as ldaps). This setting is independent
of the runtime security of the BusinessWare described in the previous sections.
To configure BusinessWare to run LDAP over SSL (ldaps):
1. Make sure the directory server is properly configured to accept SSL
connection on a secure port (typically 636).
2. Set the ssl_capath parameter in VTPARAMS to point to the CA certificate
of the CA that signed Directory Servers certificate.
3. Modify the value of the BWROOT parameter in VTPARAMS to use the ldaps://
protocol and the secure port. For example:
ldaps://myhost:636/cn=bserv1,o=mydomain
Refer to Appendix A, Environment Variables, Registry Items, and System

Files, for more information on VTPARAMS.

5 5 ADMINISTERING DATABASES
This chapter describes how to administer databases to work with BusinessWare.

Topics include:
! BusinessWare Database Overview
! Configuring IBM DB2 Databases
! Configuring MSSQL Server 2000 to Support JTA
! Sybase Configuration Notes
! XA Configuration for Oracle
BUSINESSWARE DATABASE OVERVIEW

The Integration Server provides a persistence service, which is used to store
objects in relational databases. This service is based on an Object-Relational
(O-R) mapping tool, which is part of the Integration server runtime. Database
tables are created, if necessary, by this tool when the Integration Server starts up
for the first time.
The BME allows modelers to build integration models, which have persistent
state. These integration models have stateful process models, which maintain their
state in Business Process Objects (BPO). The Integration server provides a
persistence service, which uses the O-R tool to persist these objects in relational
databases. When timers are created in process models, they are also persisted in
the database. Activities and tasks in BusinessWare Task Manager projects are also
stored persistently using this service.
Transactional source connectors use the persistence service to keep track of their
state. Source connectors typically keep track of the last event successfully
processed. This ensures that source connectors do not resend the same event twice
in the presence of server crashes.
In summary, the following objects are persisted:
1. Application state
a. BPOs in process models
b. Data Objects (DO)

ADMINISTERING DATABASES
BusinessWare Database Overview
c. Timers in process models

d. Tasks and activities in BusinessWare Task Manager projects
2. Connector state
a. Channel position is stored here when a channel source is used
3. Integration Server internal state
a. In-doubt transactions
b. Next available service-id for remote objects created by the Java
Transaction Service (JTS) subsystem in the transaction manager
c. Target connector transactional state
Objects in categories (1c), (1d), (2), and (3) are considered internal to
BusinessWare and database tables for those objects should modified only with
extreme care. In addition, BusinessWare-specific, that is, noncustomer-specific,
fields of BPOs are also considered internal and should also be modified with
extreme care.
The persistence manager is configured as part of the Integration Server

configuration. Refer to the Integration Server configuration section in the
deployment chapter of the BusinessWare Modeling Guide. Multiple Integration
Servers can share the same database.
Note: Database reserved words cannot be used in the declaration of logging
schema. Because database reserved words vary from database to database, it is
best to avoid words that may be reserved in order to increase database
independence. Prefixing columns with a string or suffixing with something such
as '_' is a good way to ensure that they do not conflict with database reserved
words.
TABLE NAMES AND PREFIXES

Table names for BPOs and DOs are provided by the modeler during design time
as part of the Object Table associated with a stateful process model. The table
names for BusinessWare internal tables are fixed. The O-R mapping tool keeps
track of the Java implementation classes and table names in the following meta-
tables:
! vitria$tablekeeps track of the Java implementation class and the table
name. There is an entry for every table used by BusinessWare.
! vitria$columndescribes the logical schema for the table. There is an
entry for every <table, column> pair.
! vitria$tableidused to store the next unique ID. This table has only one
row. This is for non-Oracle databases only.

The portion of the table name until the $ sign is the table prefix. The prefix is a
property of the persistence manager that can be set using the BME. The O-R
mapping tool prefixes every internal table (except those in category 1c) with this
prefix.
Note: BPO tables are never prefixed.
If the prefix you set in the persistence manager during deployment is myPrefix,
then the above tables names will be myPrefix$table and myPrefix$column.
For the rest of the chapter, assume that the prefix is set to vitria.
Note: The default setting of the prefix property is the empty string . In that
case, only the persistence managers meta-tables (vitria$table,
vitria$column, vitria$tableid) are prefixed by vitria. The remaining
internal tables are not prefixed.
BPOS AND DOS

BPOs are associated with stateful process models, and DOs are associated with
both stateful and stateless process models. These are defined using CORBA IDL.
The persistence service is responsible for implementing the O-R mapping. The
database tables will be created, if necessary, when the server starts up for the first
time. The persistence service is responsible for loading and storing the objects
from the relational database using the O-R mapping tool.
The physical schema of these tables can be tuned depending on the specific
application. Users can rename these tables, change sizes of various columns, and
apply indexes to various columns. However, they cannot modify the logical
schema.
TRANSACTION MANAGER STATE

The transaction manager service in the Integration Server uses a table to manage
its internal state. Each row logs information about a specific transaction that is
in-doubt. Log entries are inserted once the commit process begins, and are deleted
when the commit process has completed reliably. There is one row per in-doubt
transaction.
The transaction manager performs crash recovery when the Integration Server
starts up. It reads all transactions that correspond to the Integration Server, and
drives recovery against those transactions.
The table name can be determined from the row in vitria$table

corresponding to implementation class name
com.vitria.services.jta.TransactionLogRecordImpl.

The transaction manager has an additional table for obtaining the next unique
service ID for exporting Object Transaction Service (OTS) Coordinator and
Recovery objects. The next available unique ID is stored in a database. The
database has only one row.

com.vitria.services.jts.serviceId.
CONNECTOR STATE
Source and target connectors may be stateful. One example is the channel source,
which persists the location of the last consumed event. This state is stored in the
database and committed as part of the global transaction that source connector is
participating in.
The table name is vitria$vtconnectorstate.
CONNECTOR TRANSACTION ID MAP

Connectors participate in a global distributed transaction as specified in JTA.
However not all foreign applications and resource managers natively support the
JTA specification. Therefore we must map the JTA transaction id to the foreign
application or Resource Managers transaction id. This map has to be persisted so
that crash recovery can be implemented.

com.vitria.connectors.framework.common.XidMap.
TIMER TABLES
Timers can be created from within process models as part of the action code in a
given transition. These timers are persisted in the database as part of the global
transaction involving that process model instance.
The table name is vitria$processtimer.
TASKS AND ACTIVITIES

There are several tables related to BusinessWare Task List. The following is a
brief description of each of them. All of these should be considered to be
BusinessWare internal tables.

Configuring IBM DB2 Databases
ActivityRecordData
The table vitria$ActivityRecordData holds all active activity instances
for a model. This table is created when a BPO enters an activity state the very first
time.
Note: The ActivityRecordData table is prefixed. The other tables are BPOs and
DOs and, therefore, not prefixed.
Task Manager Tables

The Task Manager is a prepackaged project that manages human-based activities
and tasks. When a BPO enters an activity state, the process model component
determines, based on the activity assignment, which Task Manager project is to
manage that activity. The process model component then dispatches the activity
to the responsible Task Manager project, which, in turn, creates an activity
instance representing the run-time instance of that activity.
The activity instance (or activity) by itself is a predefined BPO, which later creates
one or multiple task instancesone for each individual performer. Each task
instance or task is another predefined BPO used to record progress made by each
individual performer. Upon completion of an activity, the Task Manager project
notifies the process model component for the original BPO to move on to the next
states. Activities and tasks are stored in the database of the Task Manager project.
The following are some of the tables for Activity instances: Activity,
Activity$dataset.
The following are some of the tables for Task instances: Task,
Task$refDataItems.
The NotificationData table stores the performer notification information for the
activity.
CONFIGURING IBM DB2 DATABASES

To configure IBM DB2 to run with BusinessWare:
1. Install the DB2 components you want as described in your DB2
documentation.
2. Run usejdbc2.bat in DB2_INSTALL_DIR\SQLLIB\java12 to configure
a JDBC2.0-compliant driver.
3. To catalog a remote DB2 database server as a local system ODBC datasource,
do the following:

Configuring IBM DB2 Databases
a. Run the IBM DB2 Client Configuration Assistant.

b. Click Add in the right side of the window.
c. Select Manually configure a connection to a database in Add Database
Wizard and click Next.
d. In Protocol palette, choose TCP/IP and click Next.
e. Input the remote DB2 database servers host name and port number. The
default is 50000. Click Next.
f. Input the database name of the remote DB2 database server.
g. Click Finish.
INCREASING BUFFER POOL AND TABLE SPACE

By default, DB2 uses a Buffer Pool and Table Space with a page size of 4k. Some
applications, such as ActivitySample or RFQSample, require page size of 32k or
table creation for BPOs fails. The following instructions describe how to
configure Buffer Pool and Table Space with larger page size:
1. Open a DB2 Control Center administration client and point to the database you
are going to work with first.
2. Right-click on the Buffer Pools node under a database and choose the create
menu item.
3. In the Create Buffer Pool dialog window, fill in the Buffer pool name field;
change the page size from default size 4 to 32. Click OK.
4. After you create the Buffer Pool, restart the database server before you create
the Table Spaces; otherwise, the Table Space will not be able to use the new
Buffer Pool.
5. Right-click on the Table Spaces node under the same database and choose the
Create > Table Space menu item.
6. In the pop-up Create Table Space dialog window, fill in the Table space name
field.
Note: The procedure described above is for DB2 7.2 Control Center
users. DB2 8.1 Control Center uses a different UI (a wizard instead of a
dialog) to configure table spaces.
7. Click on the Advanced button in the right-bottom to display an Advanced
dialog window pop-up.
a. Change the page size from default 4 to 32.
b. Change the Buffer pool from default IBMDEFAULTBP to the newly
created Buffer Pool with page size 32.

Configuring MSSQL Server 2000 to Support JTA
c. Then click OK in the Advanced dialog window.

8. Go back to the Create Table Space window, click Add on the right. Then
configure a new directory for the newly created table space, so that all the
database data corresponding to it will be written into.
9. In order for the new settings to take effect, you may need to restart the database
server.
Note: In the runtime, DB2 server creates tables of different table space
according to the record size.
AVOIDING -911 ERRORS

When running BusinessWare applications with DB2 as persistence store, you may
get DB2 911 errors (deadlock exception) which sometimes force the shutdown
of the BusinessWare Server. This problem is caused by DB2s next key locking
mechanism. The next key locking guarantees a Repeatable Read (RR) isolation
level by automatically locking the next key for all INSERT and DELETE
statements and is the DB2 UDB default.
If you do not have any applications using the Repeatable Read, you do not need
to use the next key locking mechanism. You can set the DB2_RR_TO_RS registry
variable on as follows:
db2set DB2_RR_TO_RS=YES
db2 force applications all
db2stop
db2start
CONFIGURING MSSQL SERVER 2000 TO SUPPORT JTA

To use JDBC distributed transactions through DataDirect type 4 driver (Connect
JDBC 3.0) on MSSQL Server 2000, you should install the SQL Server JDBC XA
procedures. The following procedure must be repeated for each SQL Server
installation involved in a distributed transaction.
Note: For further information about configuring MSSQL Server 2000, see the
%VITRIA%\data\install\support_utils\README file. You need to
copy the instjdbc.sql and sqljdbc.dll files from the support_utils
directory to your <SQL2000 directory>\MSSQL\bin directory before you can
run the configuration command.

Sybase Configuration Notes
1. Back up your master database.

2. At a command prompt, use the following syntax to run the instjdbc.sql
script provided with your MSSQL Server 2000 product:
ISQL -Usa -Psa_password -Sserver_name
-ilocation\instjdbc.sql
where:
" sa_passwordis the password of the system administrator.
" server_nameis the name of the server on which SQL Server resides.
" locationis the full path to instjdbc.sql.
3. The instjdbc.sql script generates many messages. In general, these
messages can be ignored; however, you should scan the output for any
messages that indicate an execution error. The last message should indicate
that instjdbc.sql ran successfully. The script fails when there is not
enough space available in the master database to store the JDBC XA
procedures or to log changes to existing procedures.
4. Start the Distributed Transaction Coordinator services if it has not been
started. Set the startup type to automatic if it set to manual.
5. The Merant SequeLink 5.2 Server is not needed for the DataDirect type 4
driver to function correctly. You can safely uninstall it if you have installed it.
SYBASE CONFIGURATION NOTES

Note the following issues when configuring BusinessWare to run with a Sybase
database:
! BusinessWare uses the Sybase JDBC driver jConnect 5.2 for Sybase Adaptive
Server 12. To support crash recovery, this driver requires that Sybase patches
EBF 9747 and EBF 9852 be installed. If these patches are not installed, then
application data may be lost if the Integration Server crashes at certain critical
times during the commit process. The patches can be downloaded from
http://downloads.sybase.com.
! When running an Integration Server that uses Sybase 12 for persistence, the
fully qualified names of connectors must be less than 255 characters.
! For Sybase 12, row sizes in all tables should not exceed 2k.

XA Configuration for Oracle
XA CONFIGURATION FOR ORACLE

If Oracle is used for Integration Server persistence, the Oracle user specified in the
database resource must have either DBA privilege or the following set of
permissions:
Table 5-1 DBA Privileges

TABLE_NAME PRIVILEGE
DBA_2PC_PENDING SELECT
DBA_PENDING_TRANSACTIONS DELETE
DBA_PENDING_TRANSACTIONS INSERT
DBA_PENDING_TRANSACTIONS SELECT
DBA_PENDING_TRANSACTIONS UPDATE
DBA_PENDING_TRANSACTIONS REFERENCES
DBA_PENDING_TRANSACTIONS ON COMMIT REFRESH
DBA_PENDING_TRANSACTIONS QUERY REWRITE
DBA_PENDING_TRANSACTIONS DEBUG
DBA_PENDING_TRANSACTIONS FLASHBACK
JAVA_XA EXECUTE
V$PENDING_XATRANS$ SELECT
V$XATRANS$ DELETE
V$XATRANS$ INSERT
V$XATRANS$ UPDATE
V$XATRANS$ REFERENCES
V$XATRANS$ ON COMMIT REFRESH
V$XATRANS$ QUERY REWRITE
V$XATRANS$ DEBUG
V$XATRANS$ FLASHBACK
V$XATRANS$ SELECT
The following system privileges are also needed for this database user:
! CREATE TABLE
! CREATE SESSION

XA Configuration for Oracle
! CREATE SEQUENCE
! FORCE TRANSACTION

6 6 ADMINISTERING WEB SERVERS
This chapter describes how to administer Web servers in BusinessWare and

includes the following topics:
! Admin Web Server
! Web Server/Servlet Engine in Integration Server
! Deploying Vitria Web Applications in Web Servers
! Setting Up Web Applications for Single Sign-On
! Setting Session Time-Out
BusinessWare bundles a Web server and servlet engine for running BusinessWare
Web applications. BusinessWare has two categories of Web server/servlet
engines:
! Admin Web ServerThis is the standalone Web server/servlet engine for
running only the BusinessWare Web Administration applications.
! Web server/servlet engine bundled inside the Integration ServerA Web
server/servlet engine can be started inside every Integration Server for running
the Web components in projects (Web Service proxies or HTTP connectors)
and for running other Vitria Web applications like Business Cockpit and
BusinessWare Task List.
ADMIN WEB SERVER

The Admin Web Server is the bootstrap Web server used for running the
BusinessWare Administration Web application. It is installed in
$VITRIA/web/adminserver. On Windows, a service wrapper is provided to
start and stop the Admin Web Server. On Solaris, HP-UX, and AIX, the Admin
Web Server can be started and stopped using the following scripts:
$VITRIA/bin/<platform>/startadminwebserver.sh
$VITRIA/bin/<platform>/stopadminwebserver.sh
where <platform> is the name of the platform (Solaris, HP-UX, AIX).

ADMINISTERING WEB SERVERS
Admin Web Server
The Admin Web Server configuration file can be found at

$VITRIA/web/adminserver/conf/server.xml. For more configuration
information refer to http://jakarta.apache.org/tomcat/tomcat-
4.1-doc/config/index.html.
CONFIGURING THE ADMIN WEB SERVER TO RUN IN SSL MODE

To configure the Admin Web Server to run in secure (SSL) mode:
1. Edit the $VITRIA/web/adminserver/conf/server.xml file to
uncomment the lines for an SSL HTTP/1.1 Connector:




<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="100" debug="0" connectionTimeout="20000"
useURIValidationHack="false" disableUploadTimeout="true" />
2. The Admin Web Server looks for ssl_certificate, ssl_privkey, and

ssl_capath parameters from the .vtparams file when it starts in HTTPS
those locations contain the appropriate files. See Configuring BusinessWare
for SSL on page 4-30 for more information.
3. Start/restart the server.
This configuration ensures that the Admin Web Server uses BusinessWare
certificates. For more information on how to set up the BusinessWare certificates,
see Secure Communication Using SSL on page 4-25.

Web Server/Servlet Engine in Integration Server
LOGGING
The Admin Web Server is configured by default to log to the file
$VITRIA/logs/adminwebserver.log with the trace level set to NORMAL.
This configuration information is specified in the following section of the server
configuration file ($VITRIA/web/adminserver/conf/server.xml):
<Listener className="com.vitria.web.server.WebserverLifecycleListener"
traceout="name=$VITRIA/logs/adminwebserver.log,type=file,binary=false,maxsiz
e=5000000,numbackups=1,flushaftermessage=true,idprefix=false,shorttimeprefix
=true,sourceprefix=false,timeprefix=false,categoryprefix=false,encoding=UTF-
8,threadprefix=true" tracelevel="globaltracelevel=normal"/>
Note: All the output to the standard console and standard error are captured in
this file: $VITRIA/logs/adminwebserverconsole.log.
WEB SERVER/SERVLET ENGINE IN INTEGRATION SERVER

A Web server/servlet engine can be started in an Integration Server to run Vitria
Web applications such as BusinessWare Task List and Business Cockpit. It can
also be used to run project components such as HTTP Connectors and Web
Services. The Web server/servlet engine can be enabled on the Integration Server
by setting the following property via the BusinessWare Web Administration tool
or from the BME during modeling.
Table 6-1 Integration Server Properties

Integration Server Description Values Default
Property
Enable Web Server Determines which type None: The Integration Server does not run None
of Web server the any Web component.
Integration Server runs. Internal: The Integration Server runs an
internal Web server and servlet engine.
External: The Integration Server runs a
servlet engine that will talk to an external
Web server.

If the Web server is enabled on the Integration Server, it has a corresponding home
directory on disk. The home directory for any Integration Server would be:
$VITRIA/web/servers/<bserv-name>/<integration-server-
name>
where <bserv-name> is the common name of the Integration Servers

BusinessWare Server and <integration-server-name> is the common
name of the Integration Server. For example, an Integration Server named
RFQSampleServer started by a BusinessWare Server named bserv1 would
have the home directory
$VITRIA/web/servers/bserv1/RFQSampleServer.
The home directory contains a directory called webapps where all non-project-
based Web applications are loaded by the Web server on startup. All project-based
Web applications are named <projectname>-<projectversion>. For example, the
Web application for RFQSample project with version initial is called
RFQSample-initial. The project-based Web applications are started when the
project is started and stopped when the project is stopped.
Apart from loading Web applications from the home directory every Integration
Server also loads applications in another location:
$VITRIA/web/common/webapps. Any Web application installed here is run
on every Web server-enabled Integration Server that is started on that machine. (If
the Enable Web Server property is turned off, the Web applications are not
started.)
INTERNAL WEB SERVER MODE

In this mode, the Integration Server runs both an internal Web server as well as a
servlet engine. Table 6-2 shows the configuration properties in this mode.
Table 6-2 Internal Web Server Properties

Internal Web Server Description Values Default
Property
Protocol Protocols that are supported by the Web HTTP, HTTPS, Both HTTP
server.
HTTP Port The port on which http requests are Any positive integer 8081
accepted.
HTTPS Port The port on which https requests are Any positive integer 8444
accepted.
MaxThreads The maximum number of threads to be Any positive integer 20
created to service Web requests greater than 5

The properties can set via the BusinessWare Web Administration or via the BME
during modeling time.
Running an Internal Web Server in HTTPS Mode

To configure an Integration Server to run an internal Web server in HTTPS mode:
1. Change the Protocol property of the internal Web server to be HTTPS.
2. The internal Web server looks for ssl_certificate, ssl_privkey, and
ssl_capath parameters from the .vtparams file when it starts in HTTPS
those locations contain the appropriate files. See Configuring BusinessWare
for SSL on page 4-30 for more information.
3. Start/restart the project containing the Integration Server.
EXTERNAL WEB SERVER MODE

In this mode, the Integration Server merely runs a servlet engine that can service
forwarded requests from external Web servers. In this mode, the servlet engine
accepts forwarded requests using AJP 1.3 protocol.
Table 6-3 External Web Server Properties

External Web Description Values Default
Server Property
Redirection Protocol Protocols supported for redirection from AJP (Currently a read only AJP
external Web servers. property)
Redirection port The port on which forwarded AJP Any positive integer 8010
requests are accepted
MaxThreads The maximum number of threads that Any positive integer greater 20
are created to service the forwarded than 5
Web requests.
The supported Web servers in this mode include IIS and Apache.
Obtaining the Web Server Redirector

BusinessWare currently supports the JK1.2 redirector that implements the AJP13
protocol. The following link connects to a page where you can find both the
binaries and the source of the JK1.2 Web Server redirectors:
http://jakarta.apache.org/site/sourceindex.cgi

Note: Pre-built binaries of the redirectors are available for some platforms; you
need to build your own binaries from the source for other platforms.
Configuring the Web Server Redirector

This section briefly explains the configuration process.
Note: The instructions here are high-level and that more detailed setup and
configuration information can be found in the document:
http://jakarta.apache.org/tomcat/tomcat-4.1-
doc/config/jk.html
This document explains the setup process for both Apache and IIS.
The setup and configuration process involves the following steps:

1. Install the mod_jk redirector in the external Web server. On IIS, the redirector
needs to be installed as an ISAPI filter in IIS (as explained in detail in the
Apache document). For more elaborate instructions on installing the redirector
on IIS, go to
http://www.getnet.net/~rbarr/TomcatOnIIS/default.htm..
For the Apache Web server, the installation is done by adding the following
directive to the server configuration file httpd.conf (in this document, the
server configuration file always refers to the httpd.conf file in the
<apache_install_dir>/conf directory):
LoadModule jk_module <location_of_the_redirector>
Note: The redirector may be placed anywhere on your hard disk, but you
should place it in the <apache_install_dir>/conf directory.
2. Configure the redirector.
a. Specify all the servlet engines that can handle forwarded requests:
This is done for Apache and IIS redirectors via a configuration file called
worker.properties. Any servlet engine that can service requests
forwarded by the redirector is a worker to the redirector. The hostname and
port name constitute a unique worker, which is assigned a symbolic name.
The following is an example of a simple worker.properties file.

worker.java_home=<jdk_location>
# list all the workers

worker.list=IntegrationServer1, IntegrationServer2
# Subsequently define each worker property
# indicates IntegrationServer1 handles ajp13 requests

worker.IntegrationServer1.type=ajp13
# indicates the port IntegrationServer1 is running on
worker.IntegrationServer1.port=<port_number>
# indicates the host IntegrationServer1 is running on
worker.IntegrationServer1.host=<hostname>
# indicates IntegrationServer2 handles ajp13 requests

worker.IntegrationServer2.type=ajp13
# indicates the port IntegrationServer2 is running on
worker.IntegrationServer2.port=<port_number>
# indicates the host IntegrationServer2 is running on
worker.IntegrationServer2.host=<hostname>
The ajp13 Worker Properties section in document

http://jakarta.apache.org/tomcat/tomcat-3.3-
doc/Tomcat-Workers-HowTo.html explains the properties in more
detail.
b. Specify which URL patterns need to be forwarded to which servlet engine.
Essentially this is mapping of the URL to the symbolic names of workers
specified in the worker.properties file.
The redirector for IIS looks up this information from the file
Uriworkermap.properties. An example of a simple
uriworkermap.properties is given below:
/cockpit/*.jsp=IntegrationServer1
/cockpit/servlet/*= IntegrationServer1
/cockpit/*.bws= IntegrationServer1
For the Apache server, the URL mapping is added to the server
configuration file:
JkMount /cockpit/*.jsp IntegrationServer1
JkMount /cockpit/servlet/* IntegrationServer1
JkMount /cockpit/*.bws IntegrationServer1
The above mappings tell the redirector to forward all dynamic requests to
Cockpit to the Integration Server1 that is defined in the
worker.properties file.

When the servlet engine is started in external mode in the Integration

Server, the application mapping files are automatically created at
<IntegrationServer-Home>/conf/auto directory:
# apache_mod_jk.confcontains the configuration for the Apache
Web server redirector to route all the requests (static and dynamic) for
Web applications running inside the Integration Server servlet engine.
# apache_dynamic_mod_jk.confcontains the configuration for
the Apache Web server redirector to route all the dynamic requests for
Web applications running inside the Integration Server servlet engine.
On the Windows platform, two additional files are created:
# iis_uriworkermap.propertiescontains the configuration for
the IIS Web server redirector to route all the requests (static and
dynamic) for Web applications running inside the Integration Server
servlet engine.
# iis_dynamic_uriworkermap.propertiescontains the
configuration for the IIS Web server redirector to route all the dynamic
requests for Web applications running inside the Integration Server
servlet engine.
The URL mapping pattern for various Vitria Web applications is discussed
in more detail in Deploying Web Applications in External Web Server
Mode on page 6-12.
Note: The redirector configuration files may be placed anywhere on your
hard disk, but it is recommended that you place them in the
<apache_install_dir>/conf directory.
3. Once the configuration files are created, the last step is to point the redirector
to the appropriate configuration files.
This is done for the IIS Web server redirector by setting up a few registry
entries:
REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software
Foundation\Jakarta Isapi Redirector\1.0]
"extension_uri"="/jakarta/isapi_redirector.dll"
//Make sure this matches the name of the IIS web
server redirector
"log_file"="<logfile_location>"
"log_level"="debug"
"worker_file"="<worker.properties_location>"
"worker_mount_file"="<uriworkermap.properties_locat
ion>"

Deploying Vitria Web Applications in Web Servers
For the Apache Web server redirector, this is done by adding the following
directives to the Apache Web server configuration file:
LoadModule jk_module <location_of_the_redirector>
JkWorkersFile <location_of_workers.properties_file>
JkLogFile <log_file_location>
JkLogLevel debug
DEPLOYING VITRIA WEB APPLICATIONS IN WEB SERVERS

The following sections describe how to set up Vitria applications in Web servers.
BUSINESSWARE TASK LIST

The BusinessWare Task List files are by default configured to under the Task
Managers Integration Server (TMServer in the TaskManager project). The
BusinessWare Task List currently runs under the ROOT Web application of the
Task Manager. The files can be found under the location
$VITRIA/web/servers/bserv1/TMServer/webapps/ROOT/awi.
Note: bserv1 is the default name of the BusinessWare Server and may be
changed during installation.
In addition, the ROOT Web application deployment descriptor contains the

following entry for BusinessWare Task List.
<servlet>
<servlet-name>
bservlet
</servlet-name>
<display-name>
bservlet
</display-name>
<servlet-class>
com.vitria.bservlet.BServlet
</servlet-class>
<init-param>
<param-name>
id
</param-name>
<param-value>
servlet0
</param-value>
</init-param>

<init-param>
<param-name>
configFile
</param-name>
<param-value>
$VITRIA/data/install/bservlet.xml
</param-value>
</init-param>
<init-param>
<param-name>
secure
</param-name>
<param-value>
false
</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>bservlet</servlet-name>
<url-pattern>*.bws</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>
60 
</session-timeout>
</session-config>
<welcome-file-list>
<welcome-
file>external/pages/TasklistGreeting.jsp</welcome-file>
</welcome-file-list>
To install BusinessWare Task List to a new Integration Server in addition

to TMServer:
1. Enable and configure a Web server on the Integration Server; you should use
a different port than 8091 used by TMServer.
2. Copy $VITRIA/web/servers/<bserv-
name>/TMServer/webapps/ROOT/awi under
$VITRIA/web/servers/<bserv-name>/<new-integration-
server>/webapps/ROOT.

3. Copy $VITRIA/web/servers/<bserv-
name>/TMServer/webapps/ROOT/WEB-INF/web.xml under
$VITRIA/web/servers/<bserv-name>/<new-integration-
server>/webapps/ROOT/WEB-INF.
Note: The new instance of BusinessWare Task List uses the same
bservlet.xml in which AWI is configured. It is also possible to configure the
new instance of BusinessWare Task List to run on an Integration Server under a
different BusinessWare Server than the default. To access the new instance of
BusinessWare Task List, use this URL (assuming HTTP protocol):
http://<hostname>:<port>/awi where <hostname> is the machine
where the new Integration Server is running and <port> is the port specified in
step 1.
BUSINESS COCKPIT
The Business Cockpit runs as a separate Web application inside the servlet engine.
It is by default installed under the directory
$VITRIA/web/common/webapps/cockpit. All Web applications under this
directory can run inside every Web server-enabled Integration Server running on
the machine.
To run Business Cockpit only on a particular Integration Server (instead
of all Integration Servers):
1. Enable and configure a Web server on the Integration Server; you should use
a special port number.
2. Move $VITRIA/web/common/webapps/cockpit to
$VITRIA/web/servers/<bserv-name>/<integration-server-
name>/webapps.
To access this instance of Business Cockpit, use this URL (assuming HTTP
protocol): http://<hostname>:<port>/cockpit
where <host name> is the machine where the Integration Server is running and
<port> is the port specified in step 1.
WEB ADMINISTRATION
The Web Administration application is a separate Web application and runs under
the Admin Web Server. It is installed in
$VITRIA/web/adminserver/webapps/webadmin.

DEPLOYING WEB APPLICATIONS IN EXTERNAL WEB SERVER MODE

When running in both internal and external Web server mode, the Integration
Server can serve BusinessWare Web applications. In the external mode:
1. The external Web server can be made to forward all requests to the Web
applications to the servlet engine in the Integration Server.
a. If the external Web server is IIS, make the following entries to the worker
mount file for each Web application.
For Business Cockpit:
# /cockpit=<worker-name>
# /cockpit/*=<worker-name>
For BusinessWare Task List:
# / =<worker-name>
# /*=<worker-name>
For Web Administration:
# /webadmin=<worker-name>
# /webadmin/*=<worker-name>
b. If the external Web server is Apache, add the following entries to the
appropriate virtual host entry in the Apache configuration file.
# JkMount /cockpit <worker-name>
# JkMount /cockpit/* <worker-name>
# JkMount / <worker-name>
# JkMount /* <worker-name>
For Web Administration:
# JkMount /webadmin <worker-name>
# JkMount /webadmin/* <worker-name>
2. The external Web server can be made to forward only dynamic requests alone
to the servlet engine in the Integration Server while handling all the static
requests by itself.
a. If the external Web server is IIS, add the following entries to the worker
mount.
# /cockpit/*.jsp=<worker-name>
# /cockpit/*.bws=<worker-name>
# /cockpit/*.do=<worker-name>

A virtual directory called cockpit also needs to be created in the IIS

server that points to the cockpit directory.
# /*.jsp=<worker-name>
# /*.bws=<worker-name>
A virtual directory called awi also needs to be created in the IIS server that
points to the BusinessWare Task List directory.
For BusinessWare Web Admin:
# /webadmin/*.jsp=<worker-name>
# /webadmin/*.bws=<worker-name>
A virtual directory called webadmin also needs to be created in the IIS
server that points to the Web Administration directory.
b. If the external Web server is Apache, add the following entries to the
appropriate virtual host directive in the Apache configuration file.
# Static files
Alias /cockpit <cockpit-location>
JkMount /cockpit/*.jsp <worker-name>

JkMount /cockpit/*.bws <worker-name>
JkMount /cockpit/*.do <worker-name>
# Static files
Alias / <awi-location>
JkMount / *.jsp <worker-name>

JkMount / *.bws <worker-name>
For BusinessWare Web Administration:
# Static files
Alias /webadmin <webadmin-location>
JkMount /webadmin/*.jsp <worker-name>

JkMount /webadmin/*.bws <worker-name>

Setting Up Web Applications for Single Sign-On
SETTING UP WEB APPLICATIONS FOR SINGLE SIGN-ON

Vitria Web applications that are configured to participate in single sign-on require
that a user login only once when using multiple applications. For example, if a
user wants to access Business Cockpit and BusinessWare Task List, it is only
necessary to login to the first application accessed. After providing a valid user
name and password to login to BusinessWare Task List, the user can go directly
to the Business Cockpit Homepage without first having to re-login to Business
Cockpit.
When users log out of a Vitria Web application, the credential cookie created
during login is removed, requiring users to enter a valid user name and password
the next time they attempt to login. Logging out of one application logs you out
of all applications. If a session times out in an application, but the single sign-on
session has not timed out, the next time you access the application that timed out,
you will not have to log in again.
Note: The Web Admin tool does not currently support single sign-on.
ENABLING SINGLE SIGN-ON

To enable single sign-on:
1. Edit the single sign-on configuration file $VITRIA/data/install/sso-
config.xml and set the appropriate properties:
<Security>


<LoginTimeout seconds="3600"/>

<UniqueID id="ssocookie"/>
</Security>
2. Enable the application to participate in single sign-on:
a. For Business Cockpit:
i. Open the following file:
$VITRIA/data/install/cockpit-bservlet.xml
ii. Search for and uncomment the following code:
<SSO configFile="$VITRIA/data/install/sso-
config.xml"/>
iii. Save the file.

Setting Session Time-Out
b. For BusinessWare Task List:

i. Open the following file:
$VITRIA/data/install/bservlet.xml
ii. Search for and uncomment the following code:
config.xml"/>
iii. Save the file.
To enable single sign-on for other Web applications, you would make similar
changes to the appropriate application-bservlet.xml file.
By default, Vitria Web applications are not configured for single sign-on.
SETTING SESSION TIME-OUT

The default session time-out for servlet applications such as BusinessWare Task
List and Business Cockpit is 60 minutes.
To change the session time-out:
1. Open the following file:
installdir/web/common/Webapps/<application>/ROOT/WEB-
INF/web.xml
2. Locate the following code and change the session timeout value:
<session-timeout>
60 
</session-timeout>

Setting Session Time-Out

7 7 ADMINISTERING BUSINESS COCKPIT
This chapter contains information on the following topics:

! Cockpit License
! Cockpit Log
! Cockpit Security
! Cockpit Server
! Configuring Cockpit Server
! Configuring Cockpit Locales
! Setting the DISPLAY Environment Variable for Unix
Note: See Setting Up Web Applications for Single Sign-On on page 6-14 for
information on how to set up Business Cockpit for single sign-on.
COCKPIT LICENSE
Business Cockpit (often referred to simply as Cockpit) requires a separate license.
It is possible to create and deploy process views without a Cockpit license, but
Cockpit users will not be able to access the views. You should confirm that the
Cockpit license exists in the VTlicenses folder.
COCKPIT LOG
Cockpit logging is part of the Integration Server log file. The Integration Server
log file is found in the following location:
$Vitria/logs
By default, the trace level is set at 3 (Normal). Higher trace levels cause more
information to be saved in the log file and increase the log file size. You should
increase the log file size when you select a higher trace level.

ADMINISTERING BUSINESS COCKPIT
Cockpit Security
To change the Cockpit trace level:

1. In the Explorer window, click on the Integration Server.
2. In the Properties window, click on the Trace Levels tab.
3. Select a trace level from the drop-down box.
COCKPIT SECURITY
Directory server administrators can set access controls on a folder for a collection
of views, or on individual views. Apply the READ permission on the LDAP view
folder node (which all the process views inside that folder will inherit), or on the
individual process view node, or on the Cockpit node, which all the view folders
and views will inherit.
IMPORTANT: Permissions set in the access control list are overwritten when a
project is redeployed.
Figure 7-1 shows an example of process views deployed in a directory server.

Figure 7-1
Figure 7-1 Directory Server Namespace

Cockpit Server
IMPORTANT: After a project is redeployed, the Cockpit administrator (that

is, BusinessWare Administrator) should reload all projects in Cockpit. See
Business Cockpit Guide for more information.
Personalizing the Cockpit Homepage requires that the BusinessWare

administrator defined in the .vtparams file has write permission on the
vt-attributes for the user and group objects in the directory server. For Sun
ONE and IBM DS directory servers, the BusinessWare installer sets these
permissions automatically. For all other directory servers, you must set the write
permission manually.
COCKPIT SERVER
By default, the Cockpit Web application runs inside of all Web-enabled
Integration Servers.
The Cockpit Web application is installed by the BusinessWare installer under the
$VITRIA/web/common/webapps/cockpit directory. Any Web
applications under $VITRIA/web/common/webapps run inside all Web-
enabled Integration Servers.
If you only want a specific Integration Server to run Cockpit, you can move the
cockpit directory from $VITRIA/web/common/webapps to
$VITRIA/web/servers/bserv-name/integration-server-
name/webapps and only that Integration Server will run the Cockpit Web
application. You can copy the cockpit directory under multiple Integration
Servers so that only those Integration Servers will run the Cockpit Web
application.
CONFIGURING COCKPIT SERVER

This section describes how to configure properties in the cockpit-
bservlet.xml file. See Chapter 6, Administering Web Servers for additional
information on configuring Business Cockpit.

Configuring Cockpit Server
COCKPIT SERVER PROPERTIES

The following properties have been added to give the Cockpit administrator better
control over its performance while considering the needs of the users:
! cockpit.views.static.dataUpdateInterval
This specifies the number of seconds between data updates of snapshot views.
Cockpit ensures that displayed data is never older than the specified interval.
A higher number leads to less frequent data updates, which results in better
cockpit performance and less performance impact to the database.
! cockpit.views.dynamic.refreshRates
This specifies the number of choices of page refresh rates presented to users.
The first number represents the duration between image updates of real-time
views. Higher numbers lead to less frequent HTTP requests. A higher first
number leads to less frequent image updates, which results in better Cockpit
performance.
! cockpit.images.retentionDuration
This specifies the number of seconds after which an expired image is removed.
A higher number leads to more images being maintained on the server and
requires more disk space.
! Charset name
This specifies the character set according to the encoding used by the browser.
The default is ISO-8859-1. Other common encodings are:
" SJIS (Japanese)
" GB2312 (Simplified Chinese)
" Big5 (Traditional Chinese)
! cockpit.encoding.applyCharset
This specifies the character set used to encode HTTP request parameters. This
is required when the request contains non ISO-8859-1 characters and the
servlet engine does not provide the encoding.
! cockpit.resource.locale
This sets the locale identifier for the Cockpit server. All responses are created
using this locale. Message strings are retrieved from the appropriately named
resource bundle.
For example, if the locale is set to zh_CN, message strings are taken from
CockpitResources_zh_CN.properties. Also, localized images are
retrieved from the appropriate sub-directory within images.
The locale provided by Cockpit is en_US.
! Single Sign On (SSO) element

Configuring Cockpit Locales
The following code determines whether SSO is used and specifies the location
of the SSO configuration file:
config.xml"/>
Uncomment this line to enable SSO for Cockpit. See Setting Up Web
Applications for Single Sign-On on page 6-14 for more information.
CONFIGURING COCKPIT LOCALES

The Cockpit locale specifies the language displayed on all Cockpit pages and the
language for all Cockpit transactions. The locale is originally set during
installation. After installing Cockpit, it is possible to change the locale to one of
the languages provided with Cockpit, or you can create a new locale.
CHANGING THE COCKPIT LOCALE

The Cockpit locale is specified in cockpit-bservlet.xml.
To change the Cockpit locale:
1. Navigate to $VITRIA/data/install and open cockpit-
bservlet.xml.
2. Set the value of cockpit.resource.locale to one of the following:
" en_US (US English)
" A user-created locale
For example:
<Property name="cockpit.resource.locale"
value="en_US" />
3. Set the value of cockpit.encoding.applyCharset to true.
For example:
<Property name="cockpit.encoding.applyCharset"
value="true" />
Note: If the servlet engine performs the character encoding for all
incoming requests, this value can be set to false if the charset is
ISO-8859-1.
4. Set the value of Charset name to one of the following:
" ISO-8859-1 (en_US)
" SJIS (ja_JA)

" GB2312 (zh_CN)

" Big5 (zh_TW)
For example:
<Charset name="SJIS" />
Note: This value should be the same as the value of
cockpit.resource.locale set in step 2.
5. Save and close the file.
IMPORTANT: On Unix, confirm that the lang variable is set to en_US or to

the locale specified in cockpit-bservlet.xml. It is important that the lang
variable is consistent with the local specified in cockpit-bservlet.xml.
CREATING A NEW COCKPIT LOCALE

Creating a new Cockpit locale requires that you modify the cockpit-
bservlet.xml file. You must also create a new file called
CockpitResources_<name>.properties, where <name> is the name of
the locale that you create.
Modifying cockpit-bservlet.xml
The Cockpit locale is specified in cockpit-bservlet.xml.
To modify cockpit-bservlet.xml:
1. Navigate to $VITRIA/data/install and open cockpit-
bservlet.xml.
2. Name your new locale. For example, if you create a locale for Swiss French,
you could name it fr_CH.
3. Set the value of cockpit.resource.locale to the locale that you
created.
For example:
<Property name="cockpit.resource.locale"
value="fr_CH" />
4. Set the value of cockpit.encoding.applyCharset to true.
For example:
<Property name="cockpit.encoding.applyCharset"
value="true" />

5. Set the value of Charset name to the appropriate value.

For example:
<Charset name="ISO-8859-1" />
Creating CockpitResources_<name>.properties
To create a new CockpitResources_<name>.properties file:
1. Navigate to $VITRIA/java/local.
2. Create a copy of CockpitResources.properties in the same directory.
3. Rename the file to CockpitResources_<name>.properties, where
<name> is the name of the locale that you specified in cockpit-
bservlet.xml.
For example:
CockpitResources_fr_CH.properties
4. Open the file and do the following:
a. Replace all resource strings with the equivalent value in the language you
specified.
For example, replace login.userName=User Name with
login.userName=Nom d'utilisateur.
Special characters such as " must be HTML encoded when the resource is
rendered by a browser.
For example, " must be encoded as ".
b. Set the value of resources.locale to the same value that you
specified for cockpit.resource.locale in cockpit-
bservlet.xml.
For example:
resources.locale=fr_CH
5. Save the new file in Unicode.
a. Run native2ascii. This utility comes with the JDK utility.
b. Place the file in $VITRIA/java/local.

Setting the DISPLAY Environment Variable for Unix
SETTING THE DISPLAY ENVIRONMENT VARIABLE FOR UNIX

To run Cockpit on a Unix platform, you must set the DISPLAY environment
variable to an XServer. If you are starting Tomcat on a remote XServer, the
DISPLAY variable needs to be set to that machine name. For example:
setenv DISPLAY 'hostname':0.0
IMPORTANT: You must set the DISPLAY variable to an XServer or Cockpit

will not generate charts.

8 8 INTEROPERABILITY WITH
BUSINESSWARE 3.X INSTALLATIONS
In BusinessWare 4.x, you can federate to BusinessWare 3.x systems by making

shortcut channel resources to BusinessWare 3.x channels. For BusinessWare 3.x
to communicate with BusinessWare 4.x, you create shortcuts the same way as in
BusinessWare 3.x (see the BusinessWare 3.x documentation on shortcuts).
Channels are the only means by which you can interoperate between
BusinessWare 4.x and BusinessWare 3.x. You can administer BusinessWare 3.x
channels through the Web Administration Tool or vtadmin. The channels are
wire-compatible, which means you can publish and subscribe to the channels from
either side.
This chapter includes the following topics:

! Configuring BusinessWare Access Control for Federation
! BusinessWare 4.x to BusinessWare 3.x Channel Federation
! BusinessWare 3.x to BusinessWare 4.x Federation
For information on using the Web Administration Tool, see Chapter 2, Using the
Web Administration Tool or the BusinessWare Administration Help. For
information on using vtadmin, see Chapter 3, Using the Command-Line
CONFIGURING BUSINESSWARE ACCESS CONTROL FOR

FEDERATION
To map BusinessWare 3.x user credentials to BusinessWare 4.xs JNDI
credential, you need to add values for vtprincipal to your user's entry in the
directory server and set a password in your BusinessWare Servers root directory
for all BusinessWare 3.x users.
Note: In general, you should configure BusinessWare access control, as
described in this section, for all federation scenarios. However, this configuration
is not required for a BusinessWare 4.x publisher to publish to a
BusinessWare 3.x channel. It is required for a BusinessWare 4.x subscriber to
subscribe to a BusinessWare 3.x channel, and all BusinessWare 3.x to
BusinessWare 4.x federation.

INTEROPERABILITY WITH BUSINESSWARE 3.X INSTALLATIONS
Configuring BusinessWare Access Control for Federation
SETTING vtprincipal AND vtbw3password IN SUN ONE

DIRECTORY SERVER
To set vtprincipal in Sun ONE Directory Server:
1. Select the user entry in the directory server.
2. Click on the Advanced Tab for this user (located near the bottom of the
console).
3. Click Add Attribute and select vtprincipal from the choices offered on
the panel; enter username:your3xname, where your3xname is your principal
user name from BusinessWare 3.x.
You also need to add an attribute to the cn=Config entry in your BusinessWare
Servers root directory to set a password for all BusinessWare 3.x users
(vtbw3password). You can set this password directly in Sun ONE or by using
the BusinessWare Web Administration tool. See Setting vtbw3password
Using the Web Administration Tool on page 8-4.
To set vtbw3password in Sun ONE Directory Server:
1. Select the root of your BusinessWare Server.
2. Double-click on the Config entry.
3. Choose vtbw3password in the panel that appears and enter the value for the
password.
SETTING vtprincipal AND vtbw3password IN ACTIVE

DIRECTORY
To set vtprincipal in Active Directory:
1. Choose Start > Program Files > Administration Tools > adsi to bring up
the adsi console.
Note: To see the adsi item on this menu, you must install BusinessWare
on the same machine as Active Directory.
2. Select the user entry in the directory server.
3. Right-click to bring up the Properties menu and click Select a property to
view.
4. Select vtprincipal.
5. In the Edit Attribute field, enter username:your3xname, where
your3xname is your principal user name from BusinessWare 3.x.
6. Click Apply.

Configuring BusinessWare Access Control for Federation
7. Click OK.
You also need to add an attribute to the cn=Config entry in your BusinessWare
Servers root directory to set a password for all BusinessWare 3.x users
(vtbw3password). You can set this password directly in Active Directory or by
using the BusinessWare Web Administration tool. See Setting
vtbw3password Using the Web Administration Tool on page 8-4.
To set vtbw3password in Active Directory:
1. Select the root of your BusinessWare Server.
2. Right-click to bring up the Properties menu and click Select a property to
view.
3. Select vtbw3password.
4. In the Edit Attribute field, enter the value for the password.
5. Click Apply.
6. Click OK.
EXAMPLE
In this example, your identification is johndoe in BusinessWare 3.x and your
identification is uid=johndoe,cn=People,cn=Company in
BusinessWare 4.x. When BusinessWare 3.x user johndoe publishes to
BusinessWare 4.xs channel from BusinessWare 3.x, the Communicator Server
needs a BusinessWare 4.x user and password for authentication. It maps
johndoe to uid=johndoe,cn=People,cn=Company by searching the
directory server for a user whose vtprincipal attribute is
username:johndoe. The server then uses the value of vtbw3password as the
password for authenticating this user. The user's password must match the value
in vtbw3password.
Note: The value of vtbw3password is set to guest by default when you
install BusinessWare.
If another BusinessWare 3.x user named jane wants to publish to
BusinessWare 4.x, then her user entry in the directory server must have the same
password as that set in vtbw3password. In effect, this is a global password for
all users who want to interoperate.

BusinessWare 4.x to BusinessWare 3.x Channel Federation
SETTING vtbw3password USING THE WEB ADMINISTRATION

TOOL
As an alternative to changing the value of the vtbw3password attribute in your
directory server, you may change the value of vtbw3password using the Web
1. Click on the BW Config button in the All Projects view.
2. Enter BusinessWare 4.x users password to use for the BusinessWare 3.x user.
This sets the value of the vtbw3password attribute on your BusinessWare
root under the cn=Config entry.
After vtprincipal and vtbw3password are set up, you are ready to publish
and subscribe from BusinessWare 3.x to BusinessWare 4.x. To reference
BusinessWare 4.x channels from BusinessWare 3.x, refer to your
BusinessWare 3.x documentation on creating shortcuts.
BUSINESSWARE 4.X TO BUSINESSWARE 3.X CHANNEL

FEDERATION
For this discussion, assume in BusinessWare 3.x you have channel Basic1 and
channel Basic2 feeding into channel Composite. You also have a channel
Replica that replicates channel Composite. The goal is to show how you can
create a folder of BusinessWare 3.x channels in the BME and how you can publish
and subscribe to it.
1. Configure the access control in BusinessWare 4.x to allow federation with
BusinessWare 3.x (see Configuring BusinessWare Access Control for
Federation).
2. Inside the BME, create a new project named Demo. Save it in the default
directory of %VITRIA%/projects/Demo.
3. At the file system level, right click and create channel resource shortcuts to the
BusinessWare 3.x channels. One method is to right-click on the project root
and select New > Resources > Channel > BW3xChannelShortcut.
Another way to create a channel shortcut is to select File > New. Then in the
Template Chooser, select Resources > Channel > BW3xChannelShortcut.
4. Rename this channel to BW317Basic1.
5. Fill in the property sheet for the shortcut channel with the Server Host Name
and Port of the BusinessWare 3.x server hosting the channel and the full path
name of the channel on the BusinessWare 3.x server.

6. The recommended way to federate channels is to put all the channels in one
project and then turn that into a dependent project that other projects can
reference. So after you create all the channel shortcuts you want, create a
deployment configuration.
Rename this deployment configuration to BW317ChannelConfig instead of
DeploymentConfiguration.
7. In the deployment configuration, partition the project and deploy it.
By default, the project is deployed both to a file and to your directory server.
The Output window displays the status of your deployment. It may look like
this:
Compiling pre-deployment project build...

Compiling DemoMain
Compiled DemoMain
INFO: Validating deployment configuration
'BW317ChannelConfig'...
Finished pre-deployment project build.
INFO: Deployment configuration validation succeeded.
INFO: Deployment succeeded.
INSTALLING THE PROJECT

To install this project to be used by others:
1. Select Tools > Install Project Module and locate the jar file created from
the deployment step above. For this example, the file is
%VITRIA%/Projects/Demo/BW317ChannelConfig.jar.
When the step succeeds, the menu status bar reads Module
BW317ChannelConfig installed.
2. Now create a new project called Test. To use the channels that are defined in
the demo project, select Project > Add Project Dependency. The Demo
project you just finished should be displayed as a choice.
3. In the BME, create a Channel Source Connector in the Editor.
You should see the property sheet shown in Figure 8-1.

Figure 8-1
Figure 8-1 Channel Source Property Sheet
4. Click on the Channel Resource and the Channel chooser panel should
display all the shortcuts created in your project. You can set the channel
resource to any one of the shortcuts (Figure 8-2.).
Figure 8-2
Figure 8-2 Selecting the Channel Shortcut

5. To test whether this setup is working correctly, create a Model (Figure 8-3).
Figure 8-3
Figure 8-3 Creating a Test Model
6. Set the Channel Sources as shown in Figure 8-4.

Figure 8-4
Figure 8-4 Setting the Channel Source

7. Set the Channel target as shown in Figure 8-5.

Figure 8-5
Figure 8-5 Setting the Channel Target
The process model simply passes the event right through.

8. In the action states entry action code, add the following code so that you can
tell that the event is going through your BusinessWare 4.x process model:
CommonMessages.logGenericTrace("automator model received

event, push it to output port.");
getOutPort().push(ctx.getEvent());
9. Deploy and start the project.
Now if you publish an event on BusinessWare 3.x to channel Basic1, this Event
is seen going through your BusinessWare 4.x process model. Then this Event is
passed back out to BusinessWare 3.xs Basic2 Channel, and both Events are
caught by BusinessWare 3.xs Composite and Replica Channels.
TROUBLESHOOTING
The following sections describe how to work around problems that may arise in
federating your servers.
Network Failures
Sometimes you may fail to connect to your BusinessWare 3.x system because of
network failures. If this happens, you may see a message similar to the following:
Example:
Compiling pre-deployment project build...

Compiling DemoMain
Compiled DemoMain
INFO: Validating deployment configuration
'BW317ChannelConfig'...

BusinessWare 3.x to BusinessWare 4.x Federation
Finished pre-deployment project build.

INFO: Deployment configuration validation succeeded.
ERROR: BW317Replica: Cannot create channel
'/Servers/w2kbserv/BW302Replica': java.lang.Exception:
Xport: Cannot connect to 10.206.233.229/7000: connection
refused.
Recreating BusinessWare 3.x Channels

If you delete and recreate a BusinessWare 3.x channel, you must recreate the
corresponding channel shortcut in BusinessWare 4.x (if it exists). You can either
deploy the project containing the shortcut or you can create the shortcut manually
using the following vtadmin command:
vtadmin create channel shortcut.
The BusinessWare 3.x channel's location is stored as an IOR in your directory

server. When you recreate the channel in 3.x, the IOR changes and there is no way
for the BusinessWare 4.x channel shortcut to know this information
automatically. The solution to this situation is to recreate the BusinessWare 4.x
channel shortcut so that it picks up the new IOR.
BUSINESSWARE 3.X TO BUSINESSWARE 4.X FEDERATION

It is possible for a BusinessWare 3.x server and application to publish/subscribe
to a channel running under BusinessWare 4.x using the following steps:
1. Configure the access control in BusinessWare 4.x to allow federation with
BusinessWare 3.x (see Configuring BusinessWare Access Control for
Federation).
2. Bring up the BusinessWare 3.x console and create a shortcut to a
BusinessWare 4.x folder or channel by entering the host and port name of the
BusinessWare 4.x server and the folder or channels path name (see the
BusinessWare 3.x documentation for more information on creating shortcuts).
Note: The BusinessWare 4.x channel must be deployed for the shortcut
to work.
At this point, BusinessWare 3.x servers and applications should be able to use the
shortcut to create publishers and subscribers to the target channel or channels
under the target folder on the BusinessWare 4.x server.

BusinessWare 3.x to BusinessWare 4.x Federation
Note: The BusinessWare 3.x console will not see updates to a BusinessWare 4.x
namespace. Thus, if you create a shortcut to a folder in the BusinessWare 4.x
namespace and then create a channel in the BusinessWare 4.x namespace under
that folder, you will need to restart the BusinessWare 3.x console to see the
BusinessWare 4.x channel. You may also see exceptions being thrown in the
BusinessWare 4.x server log while viewing its namespace from a
BusinessWare 3.x consolethese exceptions are caused by attempts to view
objects that are specific to BusinessWare 4.x and are harmless.

9 9 BACKING UP AND RESTORING FILES
You should back up BusinessWare data frequently to minimize loss if a file or

database table becomes corrupted. This chapter describes back up strategies and
procedures in these sections:
! Backup Basics
! What to Back Up
! Backup Operations
! Restoring Files
BACKUP BASICS
Most BusinessWare sites perform backups daily. To minimize the amount of data
you have to re-enter and re-process after restoring from a backup, you should also
consider backing up after making important or extensive changes.
For the ultimate in backup protection, make a complete offline backup after
testing, configuring, and initial deploying of your BusinessWare system but just
before starting the servers. Back up your application definitions and system
definitions and all of the communicator .dat files. Be sure to purge all events
from your channnels and queues backing up your communicator .dat files.
Make sure not to backup database tables or runtime events as these will
compromise your baseline backup. See the subsequent sections of this chapter for
more information on how to perform these backups.
You should back up Design Time data, such as Project files, once when you have
deployed the system and only afterwards if you make changes to the deployment.
On the other hand, you should back up runtime data, such as the directory server
and the .dat files, frequently as runtime data, by definition, changes over time.
This produces a set of baseline backup files whose known integrity might be
useful in an extreme case, for example, if the normal backup files somehow
become corrupted.
Note: Obtain a snapshot when the system is shut down. Otherwise, backups
across multiple Communicator Servers and databases may be inconsistent.

BACKING UP AND RESTORING FILES
What to Back Up
WHAT TO BACK UP
The BusinessWare components read and write the following files and database
tables, which you should back up:
Table 9-1 BusinessWare Data Stores

Component Store Backup Tool to Use
Type
BusinessWare Modeling File Use standard administrative backup tools to back up the Vitria file tree.
Environment (BME) system
BusinessWare log files
BusinessWare Design Time Use standard administrative backup tools to back up the projects created
files (projects) through the BME.
Deployment configuration, Directory Use native directory server backup tools. (See Backing Up Directory
server definitions server Server Files.)
Communicator Data .dat and See Backing Up the Runtime Environment on page 9-3.
.wal files
Integration Model Data Database Use native database backup tools. (See Backing Up Integration Model
Data on page 9-3.)
BACKING UP DIRECTORY SERVER FILES

BME Projects are deployed in the directory server. They contain both application
(e.g., integration models) definitions and system resource definitions, such as
those for the Integration Server and channels.
You should back up data stored in a directory server using tools native to the
directory sever you have chosen to implement. For more information, refer to the
administration guide for your directory server.
In general, the following instructions apply:

! If your directory server is Sun ONE, use either the console or command-line
scripts to back up your directory server data. (For Sun ONE 5.0, see
Populating Directory Databases in the administration guide available on the
Sun ONE Web site.
! If your directory server is Active Directory, use the LDIFDE and CVSDE
command-line utilities, respectively, to import and export directory
information. LDIFDE exports and imports Active Directory data. CSVDE
imports and exports data from files that are compatible with the comma-
separated variable (CSV) format used in applications such as Microsoft Excel.

What to Back Up
You can back up and restore directory server data either via LDAP native database
or the directory subtree. If you choose to back up data from the subtree, make sure
to back up the following:
1. The directory subtree under BWROOT (including the root), which includes
information for namespace, servers, projects metadata and configuration, etc.
2. Users data under LDAP_USERS.
3. Groups data under LDAP_GROUP.
IMPORTANT: Although the directory server schema data files generally do not
need to be backed up because you can always restore them from the XML files
that Vitria provides, you should back up your
config/schema/99user.ldif file. You can then reinstall this file in case of
directory server failure.
BACKING UP THE RUNTIME ENVIRONMENT

This section describes how to back up your runtime environment.
Backing Up Communicator Data

To back up Communicator Server data:
1. If the server is running, use the command:
vtadmin backup chanserv <chanserv-path> <backup-file-name>
Where <chanserv-path> is the path name of the Communicator Server (e.g.,
/Servers/chanserv1).
The backup file appears in the same directory as the original .dat file on the
server machine.
2. If the server is shut down, you can just copy the .dat file using the system
copy command.
Backing Up Integration Model Data

Integration model runtime data (BPOs for process models and connector states)
are stored in databases. The Integration Server where the project is partitioned is
configured with a persistence mechanism.
Tools provided by the database vendor can be used for backup/restore.

Backup Operations
For more information on the database tables created and used by BusinessWare,
see Chapter 5, Administering Databases.
BACKUP OPERATIONS
When you perform a backup, the entire system spanning multiple Integration
Servers and Communicator Servers must either be quiescent (i.e., no events
flowing through the system, no deployment or administrative operations ongoing)
or shut down. Otherwise, the individual Communicator Server .dat, .wal and
database backups will not be consistent.
Perform your backups in the following order:

1. Design Time files
2. Directory Server
3. .dat and .wal files
4. Database tables
RESTORING FILES
This section describes how to restore files from your backups.
RESTORATION OPERATIONS
When you restore a backup, the entire system spanning multiple Integration
Servers and Communicator Servers must either be quiescent (i.e., no events
flowing through the system, not deployment or administrative operations
ongoing) or shut down. Otherwise, the individual Communicator Server .dat,
.wal and database backups will not be consistent.
Restore your backups in the following order:

1. Database tables
2. .dat and .wal files
3. Directory Server
4. Design Time files

Restoring Files
RESTORING COMMUNICATOR FILES

BusinessWare is a a distributed system. It is also an element of a larger distributed
system that also includes connected enterprise applications. Restoring a portion of
any distributed system is inherently complicated. If you restore one component of
a distributed system, then time in effect rolls back for that component but not for
others. As a result, some operations can be repeated. For example, an order
residing in the restored component might be filled a second time. The
consequences of repeated operations that do not change system state may be
acceptable. For example, a repeated query may not cause much trouble, even if it
produces a different result than it did when it was first run. However, operations
that change system state (for example, depositing a payment) can have serious
effects if they are re-executed because of a restore. In general, restoring part of any
distributed system necessitates manual correction of some of the side effects of the
restoration. For example, if restoration causes a deposit to be made twice, you
must debit the relevant account by the amount of the deposit. Well before you
need to restore BusinessWare, you should prepare a plan for responding to side
effects, so that soon after a restoration you can bring your overall system into a
consistent state.
Note: Obtain a snapshot when the system is quiescent; otherwise, backups
across multiple Communicator Servers and databases may be inconsistent.
If the Communicator crashes, it will usually restart without difficulty. However,

if the Communicator Server refuses to start and writes a log message containing
bad magic number, then a .dat file is corrupt and must be repaired or restored
from a backup. If the Communicators .dat file is corrupt, you should first
attempt to repair it by running the chancheck utility with the -k option.
Note: chancheck may shrink the size of the .dat file. However, the restored
file is logically equivalent to the original.
The following suggestions and considerations will help you make the best use of
chancheck.
! When you run chancheck on the Communicator Server .dat and .wal files,
run it on a copy and not on your originals.
! Never move a .wal file without moving its associated .dat file.
! The .wal file is married to the .dat file. It is not possible to delete a .wal file
and leave the .dat file in a valid state. If you delete the .wal file and try to
start BusinessWare, the .dat file will be corrupted and need to be discarded.
! If a .dat file becomes corrupted, it is unlikely that you will be able to continue
running off that .dat/.wal file ever again.
! Do not delete the .wal file for any reason even if you believe it to be empty.

Restoring Files

10 10COMMAND-LINE TOOLS
This chapter lists and describes various command-line tools that are included with
BusinessWare:
! chancheck
! cschemagen
! cstubgen and jstubgen
! dtdtotype
! hidepwd
! importfrom3x
! importfrom41x
! logchanview
! registeraction
! rescomp
! showxport
! startadminwebserver
! startservs
! stopadminwebserver
! stopservs
! vtadmin

COMMAND-LINE TOOLS
chancheck
chancheck
The chancheck utility is used to compact the Communicator Server .dat file
and to repair errors. The chancheck utility parses the Communicator Servers
data file (datfile, or .dat file) to detect unused portions and then writes a copy of
the original .dat files required data structures to a new file, without the unused
spaces. The chancheck utility is useful if disk space is scarce, since the
Communicator Servers .dat file does not shrink, even if events are purged from
the channel. Once the.dat file has reached a certain size, it never gets smaller,
even if most of the space in the file is not actively used. As BusinessWare keeps
track of free space in the data file, this space can be reused.
The chancheck utility is also useful in the situation where you have copied the
chanservs .dat file, but not the .wal file, resulting in a corrupted .dat file. To
remedy the situation, run chancheck with the -k option against the
Communicator Server .dat file. The majority of events will be recovered (you
may lose a few), and you will be back in a running state.
Generally, chancheck (located in installdir/bin/platform) is run in the

directory where the Communicator Servers data (.dat) and write-ahead (walfile
or .wal file) files are located. The default directory is installdir/data, where
installdir is the installation directory.
The chancheck utility is an interactive utility; once chancheck is started from

the command-line and reads in the relevant .dat file, you may pass it a series of
commands to operate on the .dat file.
Note: Both the Communicator Server and the BusinessWare Server must be
stopped when chancheck is run.
SYNTAX
chancheck [d datfile] [w walfile] [k]
Options
-d datfile
Name of the Communicator Server data file (.dat file) to operate on. If this
option is not used, chancheck reads in chanserv1_v4.dat.
-w walfile
Name of the Communicator Server write-ahead data file (.wal file) to operate
on. If this option is not used, chancheck reads in chanserv1_v4.wal.

COMMAND-LINE TOOLS
chancheck
k
Keep trying to read the data file despite errors.
Commands
Once chancheck is started from the command line, and reads in the relevant
.dat file, you may pass it the following commands
write filename [wal_file_size]

Write the compacted data file out to filename in the current directory. filename
is a required argument. wal_file_size may be set to the same value that you use
for your production server if larger transactions are being used or if a
transaction too large error is seen when issuing a write command to
chancheck.
help
Print list of available commands.
touch
Set the arrival time of an event forward a number of seconds in the output
.dat file. This can be useful in disaster recovery from an old .dat file where
the events would have normally been purged.
quit
Exit the program.
EXAMPLE USAGE
To compact your second Communicator Servers .dat file:
1. Stop the BusinessWare service.
2. In the installdir/data directory:
a. Execute the command:
chancheck -d chanserv2_v4.dat -w chanserv2_v4.wal
b. Observe the response:
Scanning object list ... Scan complete.
c. Execute the command:
write ctemp.dat
d. Observe the response:
Wrote Object manager block...

COMMAND-LINE TOOLS
cschemagen
e. Execute the command:

quit
f. Observe the response:
Stabilizing log ...
Deleting chanserv2_v4.wal
Exiting.
3. Copy the old .dat file to a new name if desired (or delete it).
4. Rename the new, compacted file to the .dat filename expected by the
5. Restart the BusinessWare service.
cschemagen
The cschemagen utility creates the metadata initialization tables required for
remote method invocations. Every class that can be sent or received using the
Object Request Broker (ORB) must have helper functions to allow the ORB to
marshal and unmarshal each class. In Java, these classes are defined by the
Common Object Request Broker Architecture (CORBA) specification. In C++,
they are vendor-specific in their implementation details.
The input to cschemagen is the header files generated by cstubgen from

Interface Design Language (IDL) files. These Vitria-specific header files contain
comments of the form //?. The cschemagen utility takes these comments and
uses them to generate a file containing a series of declarations of the helper
functions of the form <module>_<interface>_getHelper and also static methods
to access these functions. The cschemagen utility also creates a static table of
IDL-derived classes and their helper functions. This table identifies a suitable
helper function to marshal and unmarshal it, given a metadata reference to a
particular class in C++.
IMPORTANT: If this static table is not linked in with an executable, the

executable will compile, but will fail when it tries to narrow an object reference
to a particular interface because the table was not present and was not initialized
with the other static variables. Make sure you run cschemagen on all header
files which contain any interface which may be narrowed in an application. Also,
you must link the resulting object files with the application executable.

COMMAND-LINE TOOLS
cstubgen and jstubgen
SYNTAX
cschemagen [options] input-file
Options
-out
Specifies the output file name. By default, the standard output is the output.
cstubgen AND jstubgen

The cstubgen and jstubgen utilities translate IDL and ODL specifications
into C++ and Java source code, respectively. This generated code implements
simple C++ and Java interfaces for publish-subscribe and request-reply
communications.
SYNTAX
cstubgen [options] input-file
jstubgen [options] input-file
Options
-accept odl
Specifies the input parsing should allow ODMG ODL constructs.
-file input-file
Generate code only for definitions in the specified file and do not generate any
outputs for included definitions (that is, using #include directives). This option
should be used only on an input file that has been passed through a C or C++
preprocessor. For example, on Windows 2000:
set CCCP_FLAGS= -DWIN32 -D_CONSOLE -D_AFXDLL -D_MBCS
-D_MT -I. -I%VITRIA%\include -I%VITRIA%\interdef
cccp %CCCP_FLAGS% inout.idl inout.i
jstubgen -file inout.idl inout.i
input-file must match exactly the #line directives (as a result of
preprocessing) in the input file. In the above example, this means inout.idl
must match a #line directive in the file inout.i.

COMMAND-LINE TOOLS
-inclext file-suffix (cstubgen only)

Use the given file extension for generated header files. By default, generated
header files have an .h suffix.
-implext file-ext (cstubgen only)

Use the given file extension for the generated stub files.
-prefix file-prefix (cstubgen only)

The specified file prefix, file-prefix, will be prepended to the generated header
and implementation files. By default, there is no prefix for header files and
there is an S prefix for implementation files.
-suffix file-suffix (cstubgen only)

The specified file suffix, file-suffix, will be appended to the generated header
and implementation files. By default, there is no prefix for files.
-noserver (cstubgen only)

Do not generate server skeleton classes. By default, a skeleton class is
generated for each interface. This option is relevant only for C++ code
generation; server skeletons are not generated for Java code.
-outdir output-directory
Specifies the top level output directory for generated files. By default,
generated files are placed in the same directory as the input files.
-package package-name (cstubgen only)

Generates code suitable for building a dynamic-linked library. For example, if
the flag -package MyPackage is given, then the following lines will appear
in the generated header file:
#if !defined(_MyPackage_dll)
#if defined(_WIN32) && !defined(_PROFILE)
#if defined(_MyPackage_mak)
#define _MyPackage_DLL __declspec(dllexport)
#else
#define _MyPackage_DLL __declspec(dllimport)
#endif
#else
#define _MyPackage_DLL /**/
#endif
#endif

COMMAND-LINE TOOLS
In addition, the generated code will have the word _MyPackage_DLL placed
before every extern declaration and class definition. When compiling a
dynamic-linked library that includes the generated code, the macro
_MyPackage_mak will have to be defined.
-path include-path (cstubgen only)

Directives to include other IDL files in the inputs are normally transformed
into include directives in the generated header files. For example, if
#include <idl/CosNaming.idl>
appears in the original input file, then
#include <CosNaming.h>
will appear in the generated header file.
Note: Only the base components of the IDL file names are retained in the
transformation.
This option instructs the compiler to retain more than just base components.
Specifically, path components that match the specified path include-path will
be retained. For example, the option -path idl will cause the generator to
produce
#include <idl/CosNaming.h>
in its outputs.
-compile (jstubgen only)

Automatically compiles the stubs that are generated by this command.
-home (jstubgen only)

Place the generated stub files in the $VITRIA\java\local directory.
-stubclass (cstubgen only)

Generates a client stub class for each interface. This flag is deprecated,
because cstubgen always generates client stub classes. (Previously, it
defaulted to not generating client stub classes.)
-verbose
Shows diagnostics to aid debugging.

COMMAND-LINE TOOLS
OUTPUT FILES
For each input file with a base name fname, cstubgen produces two output files:
fname.h and Sfname.cxx. The fname.h file must be processed by
cschemagen. Applications will need to include the generated header file at
compile time, and link the stub file at link time.
jstubgen produces a separate Java class (and hence, a separate file) for each
module, interface, and type definition in the input file. A module definition in the
input will cause a separate directory to be created; all the classes generated for
definitions within the module will be placed inside the directory.
Outputs generated from module level constants are placed in a Java file whose
name is _module in the module directory.
Each interface definition will cause the generation of two Java files. The first file
(with no underscores in its name) contains a Java interface definition, intended to
be implemented by concrete Java classes. The second generated file (with a
leading underscore in its name) contains the client stub implementation.
For type definitions in modules and interfaces such as structs, one Java class
(hence, one file) will be generated per definition. The name of the generated file
will match the name of the corresponding definition.
To illustrate the Java files generated by the compiler, consider the following
definitions:
module A {
struct B {
char x;
};
interface C {
exception D { };
enum E { zero, one, two };
};
};
The compiler will generate the following Java files in the following directories:
A\B.java
BHelper.java
BHolder.java
C.java
CHelper.java
CHolder.java
_C.java

COMMAND-LINE TOOLS
dtdtotype
_module.java
A\CPackage\D.java
DHelper.java
DHolder.java
E.java
EHelper.java
EHolder.java
dtdtotype
The dtdtotype utility converts a Document Type Definition (DTD) file to a
DefinedType file. Such files, which should be part of a BusinessWare project, are
used by the BusinessWare Modeling Environment (BME). In most cases, you
should use the Import Types command in the BME to create Types. However, the
-event, -noevent, and -allevent flags enable dtdtotype to perform functions that the
BME Import Types command cannot.
SYNTAX
dtdtotype [options]
Options
-out filename (required)
Specifies the name of the DefinedType file
-module modulename (required)

Specifies the target module that this tool places in the DefinedType file. It may
be a fully qualified path--for example, a/b/c.
-event elementname[,elementname,elementname,...]
Generates events for the specified element or elements only.
-noevents
Do not automatically generate events for all elements.
-allevents
Automatically generates events for all elements.
-dtd filename

COMMAND-LINE TOOLS
hidepwd
Specifies the name of the DTD file to be converted.

Note: You must specify at least one of the following flags: -dtd, -xml.
-xml filename
Specifies the name of the Extensible Markup Language (XML) document that
determines the System Identifier and/or Public Identifier to be used. In this
case, this tool generates a single event for one element, the name of which is
given in the XML document's doctype element.
Note: If you specify this flag but not the -dtd flag, this tool will use the
System Identifier in the XML document to find the DTD.
-system systemID
Specifies a System Identifier to be associated with the event or events.
-public publicID systemID

Specifies both the Public Identifier and a System Identifier (in that order) to be
associated with the event or events.
hidepwd
The hidepwd utility creates an obfuscated version of your LDAP user account
password. You can paste the output of this tool into the appropriate location within
your .vtparams file to deter unauthorized users from gaining access to your
BusinessWare installation. Though your password has been obfuscated,
BusinessWare is still able to recover the original password, and you can continue
logging into your LDAP user account using the same password.
SYNTAX
hidepwd LDAPUserPassword
EXAMPLE
The following is an example for using hidepwd.
Assume that your LDAP user account password is wound$example. This means
that your .vtparams file looks something like the lines below:

COMMAND-LINE TOOLS
importfrom3x
BWROOT="ldap://ldap1.vitria.com/cn=abc,o=vitria.com"
auth_userdn="uid=alex,ou=People,o=vitria.com"
auth_password="wound$example"ldap_users="ou=People,
o=vitria.com"ldap_groups="ou=Groups,o=vitria.com"
To obfuscate your password, type hidepwd wound$example at a command-

line prompt to get the output on the second line:
C:\>hidepwd wound$example
<YT1cAMABMD6AEglFB9iljur@Ub41Z6fddAzyKa>
To hide your LDAP user account password, substitute the output of the hidepwd
command (including the < and > characters) for the original password
(including the quote marks) as shown below, then save the result.
BWROOT="ldap://ldap1.vitria.com/cn=abc,o=vitria.com"
auth_userdn="uid=John,ou=People,o=vitria.com"
auth_password=<YT1cAMABMD6AEglFB9iljur@Ub41Z6fddAzyKa>
ldap_users="ou=People,o=vitria.com"ldap_groups="
ou=Groups,o=vitria.com"
In the future, you will still be able to log onto your LDAP user account using the
password wound$example.
Note: This tool adds randomization when it executes, meaning that it never
gives the same output twice, even for the same password.
importfrom3x
The importfrom3x utility imports runtime data migrated from BusinessWare
3.x during migration. Runtime data is generated by running exportto4x against
a BusinessWare 3.x server. There are two XML configuration files, import.xml
and params.xml related to this tool. Those two files are under
%VITRIA%\data\migration for Windows or $VITRIA/data/migration
for Unix. Before you run this tool, you need to modify params.xml and run
Tools > Migrate BW 3.x Application from the BME . For more information,
refer to the BusinessWare Migration Guide.
SYNTAX
importfrom3x

COMMAND-LINE TOOLS
importfrom41x
importfrom41x
importfrom41x imports runtime data migrated from BusinessWare 4.1.x
during migration. For more information, refer to the BusinessWare Migration
Guide.
SYNTAX
importfrom41x
logchanview
The logchanview utility is a command-line utility that displays BusinessWare
logging messages from channels. The output appears on stdout by default.
SYNTAX
logchanview [options] <channel>
Options
-o <spec>
Output specification to redirect output from the utility.
For example:
logchanview -o "type=channel,name=xxx" xxx
See Diagnostic Output Specification on page B-2 for more information on
the options for specifying an output file.
-b <name>
Extra resource bundle.
-e
Start viewing events from the end of the channel, that is, the latest events.

COMMAND-LINE TOOLS
registeraction
registeraction
The registeraction utility registers new action or translator (SDT) classes so
that the BME can display the methods they contain. After registration, the classes
and methods are visible in the BMEs Action Builder and the Code Helper. Run
registeraction after creating a new class that contains custom translation
methods for use in process models. If you add methods to the class, they will be
picked up after you restart the BME.
Note: Only public static methods of the class are available in the Action
Builder.
SYNTAX
registeraction [options] class-name1 class-name2...
Options
-a class-name1 class-name2...
Registers new action classes and methods; these classes and methods will then
be displayed in the BME.
-d class-name1 class-name2...
Removes specified action classes from the registry; they will no longer appear
in the BME.
-p
Prints all registered action classes.
rescomp
The rescomp utility compiles resource files into Java and C++ stubs. To create a
resource bundle in C++, use this tool to create C++ stubs, then compile them and
link them into a shared library.
The resourcefile file is the resource file to be used as input.
The value of target depends upon whether you are creating Java or C++ stubs. See
Specifying the Target, for details.

COMMAND-LINE TOOLS
rescomp
SYNTAX
rescomp [-chj] [-p packagename] resourcefile target
Options
-c
Specifies that C++ stubs are to be generated.
-h
Specifies that C++ headers are to be generated.
-j
Specifies that Java stubs are to be generated.
Note: Only one of the above three options can be used at a time.
-p identifier
For Java, identifier specifies the package into which the Java stubs will be
generated. For C++, identifier is the C++ symbolic identifier for the DLL.
Specifying the Target

When you use rescomp to create C++ stubs or headers, target specifies the name
of the file into which the output will be placed.
When you use rescomp to create Java stubs, it generates one Java class file for
each module in the input file. The location of these files is determined by the value
of target and by the package name given by the -p option.
The name of each class generated is given by the name of the module in the input
file followed by the string Messages.
The target argument is interpreted as a pathname from which to start, with the
period character (.) indicating the current directory. At this starting location,
rescomp generates a Java-style set of nested directories that correspond to the
reverse package name. rescomp then places the generated class file or files in
this location.

COMMAND-LINE TOOLS
showxport
Example
Suppose you have a resource file named testres.txt, and it contains a module
named MyApplication. Assume also that you want the generated stubs to belong
to the package com.vitria.testpackage, and that the folders containing the single
stub file MyApplicationMessages.java should be located in the directory
c:\aaa1. The command that causes this to happen is:
rescomp -j -p com.vitria.testpackage testres.txt
c:\aaa1
Creating a Resource Bundle

You should use the -p flag if you intend to create a resource bundle. Adding an
identifier with a value of xyz (that is, including -p xyz to the rescomp
command) causes it to create a macro named _xyz_mak within the .cxx file.
Defining this macro during the compilation of this file causes the C++ stubs to
have the correct symbolic exports, thus enabling them to be linked into a shared
library.
showxport
The showxport utility displays information about your current configuration of
your machine, including transport information, local IP addresses, and the
contents of the .vtparams file. This tool is used to diagnose communication
problems and verify the contents of .vtparams.
SYNTAX
showxport
EXAMPLE
The following shows a sample output for showxport:
Vitria Transport Layer Information:

Default character codeset [CP1252]
Hostname [mammoth]
Full hostname [mammoth.vitria.ad.vitriacorp.com]
IP address 1 of 1 [10.206.243.76]
Process ID [1540]
Real user name [john]
Effective user name [john]

COMMAND-LINE TOOLS
startadminwebserver
Parameter
BWROOT=[ldap://mammoth:389/cn=JJones,dc=vitria.com]
Parameter auth_user=[uid=JJones,ou=people,dc=vitria.com]
Parameter auth_pass=[******]
Parameter ldap_gr=[ou=Groups,dc=vitria.com]
Parameter ldap_us=[ou=People,dc=vitria.com]
Parameter lic_directory=[C:\home\john\licdir]
startadminwebserver
The startadminwebserver utility starts the Web server that hosts several
BusinessWare Web applications (Unix only).
SYNTAX
startadminwebserver
Options
None
startservs
The startservs utility starts and configures the BusinessWare Server (Unix
only).
SYNTAX
startservs [-l] [<server_name>] [-h]
Options
-l
Lists all the BusinessWare Servers.
server_name
Starts the specified BusinessWare Server.
-h
Shows the usage message.

COMMAND-LINE TOOLS
stopadminwebserver
stopadminwebserver
The stopadminwebserver utility stops the Web server that hosts several
BusinessWare Web applications (Unix only).
SYNTAX
stopadminwebserver
Options
None
stopservs
The stopservs utility stops the BusinessWare Server (Unix only).
SYNTAX
stopservs [-l] [<server_name>] [-h]
Options
-l
Lists all the BusinessWare Servers.
server_name
Stops the specified BusinessWare Server.
-h
Shows the usage message.
vtadmin
System administration tool for manipulating channels, servers, and other objects
in BusinessWare. See Chapter 3, Using the Command-Line Administration
Tool, for details.

COMMAND-LINE TOOLS
vtadmin

11 11TROUBLESHOOTING AND TIPS
This chapter provides troubleshooting information and tips on administering your

system.
! If you have out-of-memory problems running the BME, you may need to
increase the heap size for the BME. Edit the
%VITRIA%\bme\bin\ide.cfg file (on Windows) or the
$VITRIA/bme/bin/bme.sh file (on Solaris) to increase the heap size. For
example, -J-Xmx200m increases the heap size to 200 Mb.
If necessary, you may also increase the -J-Dvitria.bme.maxlogsize
and -J-Dvitria.bme.maxlogcount.
! The /admin/groups/administrators directory must be granted the
Full permissions to the BusinessWare items (such as folders, model, servers,
etc). Removal of the permissions may cause the servers fail to operate, since
the servers are running as one of the credentials in
/admin/groups/administrators when accessing these items.
! For reasons of data security, production systems should use SCSI, not IDE
hard disks.
Note: BusinessWare uses MSYNC version 2 for writing to disks.
! Timeout exceptions may occur when executing the vtadmin command to
purge large numbers of events for a channel.
Before purging the channel, change the channel's property Wait Limit to a
higher number. The default setting is 10 seconds. The correct length of the
Wait Limit depends on how many events are in the channel. Start with 30
seconds first. If that is not enough, add another 15 seconds.
! Administrators should note that using the force direct io option on remote
mounted EMC disks will possibly reduce the BusinessWare performance
while writing to log files.
! Projects must be manually restarted if BusinessWare stops or there is a system
problem. Projects are never automatically restarted.
! Be sure not to set your maximum Communicator Server .dat size to be
greater than the quantity of disk available. The largest .dat size you can set
is 4 terabytes.

TROUBLESHOOTING AND TIPS
! On Windows, you may not be able to compile a project if your Java

user.home variable has a space in the pathname. This may occur if your
HOME environment variable is not set, so you can prevent the problem by
setting the variable to a pathname that does not include spaces. Otherwise, you
can work around this problem by setting user.home in the BME startup
command. For example:
bmec.exe -J-Duser.home=d:\home

A A ENVIRONMENT VARIABLES, REGISTRY
ITEMS, AND SYSTEM FILES
This appendix lists the environment variables and registry items that configure
BusinessWare.
ENVIRONMENT VARIABLES
Environment variables are organized in the following categories:
! Vitria variablesenvironment variables specific to BusinessWare
! Additional variablesadditional environment variables required for C++
application development
! BusinessWare 3.x variablesdeprecated BusinessWare 3.x environment
variables that will continue to work in BusinessWare 4.2.1.
VITRIA ENVIRONMENT VARIABLES

Table A-1 describes the variables specific to BusinessWare.
Table A-1 Vitria Environment Variables

Name Default Value Description
VITRIA C:\Program Files\Vitria\BWversion The BusinessWare installdir
VTPARAMS If you choose to use a parameter file All other BusinessWare variables. See
(recommended), the location is user specified. The VTPARAMS below for more
default value is file="C:\Program Files information.
\Vitria\.vtparams
VTPARAMS
VTPARAMS is meant to describe all transport and communication parameters that
must be known before a process can communicate with the directory server.
VTPARAMS names and default values are shown in Table A-2.
BusinessWare Administration Guide A-1

ENVIRONMENT VARIABLES, REGISTRY ITEMS, AND SYSTEM FILES
Syntax Description
The VTPARAMS syntax is as follows:
name=value, name=value, name=value, ...
where the value may be enclosed in quotes (single or double quotes), semi-colons
may be used in place of commas, and extra white space is ignored.
Parameter Files
Since the value of VTPARAMS can become long and difficult to manage,
BusinessWare supports the use of parameter files (recommended). This feature
eases administration by allowing the user to put all parameters into one file and
direct every process to that file. The following is a sample VTPARAMS parameter
file:
file="installdir\.vtparams"
BWROOT="ldap://ldapservername.VITRIA.com:389/cn=computername
_bw,dc=VITRIA",
auth_userdn="uid=username,ou=People,dc=VITRIA",
auth_password="userpassword",
lic_directory="C:\VTlicenses",
ldap_groups="ou=Groups,dc=VITRIA",
ldap_users="ou=People,dc=VITRIA"
Optionally, BusinessWare can read from multiple files or you can specify some
parameters in VTPARAMS and some in a parameter file as the following code same
shows.
file="\Program Files\installdir\.vtparams",
file="C:/users/username/.vtparams",
auth_userdn="username", auth_password="password"
Note: If the same variable parameter is used multiple times, the last setting of
the variable has precedence.
IMPORTANT: You should use parameter files, not the VTPARAMS environment
variable, to define parameters. Use the VTPARAMS environment variable only to
point to the parameter file and to override specified file parameters.
A-2 BusinessWare Administration Guide

Figure 1-1
Table A-2 VTPARAMS Names and Default Values

auth_password "ldappassword" The password used to log into the LDAP
directory server.
auth_userdn "uid=youruserid,ou=ldapuserd, The distinguished name (DN) required to log
o=yournetworkdomain" into the LDAP directory server.
Note: Typically, ldapgroupdn="Groups"
and ldapuserdn="People"
ldap_groups "ou=ldapgroupdn,o=yournetwork The location on the LDAP directory server
domain" where groups are defined.
BWROOT "ldap://ldaphost The location in the LDAP directory server where
[:port]/cn=namespaceroot,o=you the BusinessWare namespace resides. It is
rnetworkdomain" specified in a URL format.
ldap_users "ou=ldapuserdn,o=yournetworkd The location in the LDAP directory server in
omain" which users are defined.
lic_directory C:\VTlicenses Directory containing the BusinessWare licenses
files.
lic_emailaddress No default value. The name of a valid email account on the
machine named in lic_mailhost.
Messages about license issues will be sent to the
given email address.
lic_mailhost No default value. The name or IP address of a machine which
supports an SMTP mail service.
httpproxy_host No default value The IP address of the HTTP proxy server.
httpproxy_masks No default value Subnet mask used when deciding when to proxy.
httpproxy_portnum No default value Port number of the HTTP proxy server.
orb_timeout 60 seconds Time limit that the BusinessWare Server uses in
making ORB invocations to other processes.
ssl_capath value of ssl_certificate For servers, this should be the path to the CA
certificate file. For clients, it can either point to
the directory that contains trusted CA
certificates, or to the file itself (the directory
containing the file also will be searched
automatically).
ssl_certificate null Path to my PEM-encoded certificate file.
ssl_clientauth false If true, client-side authentication will be
performed as part of SSL handshake. This option
is disabled (set to false) by default.

Table A-2 VTPARAMS Names and Default Values (Continued)

ssl_passphrase null Pass-phrase to decrypt DES-encrypted private
key file. You only need ssl_passphrase in
your .vtparams file if the private key is
password-encrypted.
ssl_privatekey value of ssl_certificate Path to my PEM-encoded private key file.
tcp_hostname No default value The hostname or IP address that a client uses to
reference a failover server.
Note: The vttcpnic attribute in your
directory server can be used to perform the same
function.
tcp_nic No default value Enables bserv to listen to an IP address.
ADDITIONAL VARIABLES
Table A-3 describes the additional environment variables required for C++
application development.
Table A-3 Additional Variable Names and Default Values

PATH .;%VITRIA%\bin\win32 Directory containing BusinessWare executables.
or
.:$VITRIA/bin/platform
INCLUDE %VITRIA%\include\ Directory containing the BusinessWare SDK C
or include files.
$VITRIA/include/
LIB %VITRIA%\lib\win32\o2r Directory containing BusinessWare libraries.
or
$VITRIA/lib/platform/lib_suffix
BUSINESSWARE 3.X ENVIRONMENT VARIABLES

The following BusinessWare 3.x environment variables will continue to work in
a deprecated mode:
! VTNAME
! VT_NIC_ADDR

Windows Registry Items
! VT_HOST_ALIAS
WINDOWS REGISTRY ITEMS

Table A-4 lists the registry items that configure BusinessWare Server and
Communicator Server instances on a Windows platform. All of the registry items
are configured by the Installer.
Table A-4 BusinessWare Registry Items

Registry Item Specifies BusinessWare Server
(Installer Reference) Default
MS Minimum heap size (MB) for the Java VM used by the 32

MX Maximum heap size (MB) for the Java VM used by the 80
params Value of VTPARAMS. file=homedir\.vtparams
(where homedir is the users
home directory)
bservdn Relative Distinguished Name (RDN) for bserv. cn=bserv1,cn=Servers
You can change bserv1 but
NOT Servers.
localadmin Forces bserv to only accept administrative No default value
commands from clients on the local machine.
Note: If no value is present, localadmin is turned off.
SYSTEM FILES
There are three types of system files used by Communicator Servers:
! Diagnostic fileprovides diagnostic information. The amount of diagnostic
information is configurable.
! Write-ahead log fileprovides transactional consistency in case the system
fails. Data lives in the write-ahead log for a short period of time before it is
written out to the data (.dat) file.
! Data fileacts as the persistent store of the server; destroying this file
destroys the servers persistent store (for example, namespace bindings or
guaranteed events).

IMPORTANT: Do not delete the write-ahead log. Data can remain in the
write-ahead log for a long time. Never assume that the write-ahead log is empty.
Note: System files cannot be shared among server instances; each instance of
BusinessWare Server and Communicator Server has its own set of system files.
The files for each instance of Communicator Server are named and differentiated
according to the naming convention provided in Table A-5. The variable instance
refers to the server instance number and version refers to the BusinessWare
version number.
Table A-5 Communicator Server System Files

File Type File Extension Communicator Server Filename
Diagnostic .log chanservinstance_version.log
Write-ahead log .wal chanservinstance_version.wal
Data .dat chanservinstance_version.dat
System files are created when a server is started, if they do not already exist. The
files of different server instances should be in different directories, or if they are
in the same directory, they must have different names.
For best performance, locate .wal and .dat files in different directories, or
preferably, locate each file on its own disk. For added insurance against data loss
in the case of hardware failure, keep the .dat file on a RAID (Redundant Array
of Independent Disks) disk. If .dat and .wal files are in the same directory, they
must have different names.
By default, the data (.dat) and write-ahead log (.wal) files are placed in the
installdir/data directory, where installdir indicates your system installation
directory. Diagnostic (.log) files are placed in the installdir/logs directory.
Note: The Communicator Server .dat file can grow very large as the server
stores a large number of events. The file can be periodically compacted to save
disk space. See chancheck on page 10-2.
To reconfigure BusinessWare:
1. Go to the Windows Control Panel and start Add/Remove Programs.
2. From the displayed list, select BusinessWare.
3. Click Change/Remove.
4. Select Reconfigure BusinessWare.

IMPORTANT: Do not delete the write-ahead log. Data can remain in the
write-ahead log for a long time. Never assume that the write-ahead log is empty.
Note: System files cannot be shared among server instances; each instance of
the Communicator Server has its own set of system files.


B B BUSINESSWARE LOG FILES
This appendix describes the various log files created by BusinessWare. Only a
subset of these log files may be present in your BusinessWare installation at any
time, depending on which BusinessWare components are being used.
The default location for all BusinessWare log files is <installdir>/logs,

except for the BME log file that is in
<installdir>/bme/settings/system.
Note: Table B-1 lists the default names for the BusinessWare log files. The
names on your BusinessWare installation may be different if you have changed
the defaults.
Table B-1 BusinessWare Log Files

Default log file name Comments
bme.log The log file created by the BME and located in
<installdir>/bme/settings/system. This log
contains errors that occur in the BME.
bserv<instance>_v4.log The BusinessWare Server log. <instance> is the instance
number of the BusinessWare Server (for example, 1).
chanserv<instance>_v4.log The Communicator Server log. <instance> is the instance
number of the communicator server (for example, 1).
deployment.log The deployment log file created by the BME, if the deployment
is done via the BME, or by vtadmin otherwise. Any errors
during deployment are logged here.
server.log The log file created by the Integration Server. Most likely the
user changes this name. For example, the name of the log file
for the RFQ sample is RFQSampleServer.log.
bservlet.log The log file created by the servlet that performs Web
administration and Task List management.
<BW server name>-tomcatserver.log The log files created when the application Tomcat Web Server
<BW server name>-tomcatservice.log starts up. Any startup errors that occur if the application Web
servers do not start are logged here.
BusinessWare Administration Guide B-1

BUSINESSWARE LOG FILES
Diagnostic Output Specification
Table B-1 BusinessWare Log Files (Continued)

Default log file name Comments
adminwebserver.log The log file created when the administration Tomcat Web
Server starts up.
Any startup errors that occur if the administration Web servers
do not start are logged here.
On Windows, additional errors are also logged in the Windows
Event Viewer.
servlet.log The log file created by the servlet that handles HTTP requests
for the HTTP source connector.
DIAGNOSTIC OUTPUT SPECIFICATION

The diagnostic output specification for BusinessWare Integration Servers can be
configured in the BME or modified after deployment using the Web Admin tool.
The diagnostic output specification for the BusinessWare Server and
Communicator Server are configured during installation. After installation, these
specifications can be changed by editing the vttraceout attribute of the server's
entry in the directory.
GENERAL SYNTAX
Diagnostic specification strings consist of a sequence of key-value pairs of the
general form:
key=value, key=value, ... ,key=value
Diagnostic specification strings are subject to the following rules:

! value can be enclosed in quotation marks, but key cannot.
! White space is ignored except when it is internal to value.
! Key matching is case insensitive.
! Keys can be abbreviated with an unambiguous prefix. For example, foo can
be used in place of fooflag so long as no other key begins with foo.
DIAGNOSTIC OUTPUT SPECIFICATION

To specify the diagnostic output, the first occurrence of key must be type. The
second occurrence of key must be name. Additional specifications of key are
optional and may depend upon the value of the first two occurrences of key.
B-2 BusinessWare Administration Guide

For example, if you are configuring the BusinessWare Server diagnostic output on
a Unix system using the startservs script, edit the BServMain -o parameter
in the startservs script to be:
type=value, name=value
The following table lists the allowed entries for key and value to configure
diagnostic output.
Table B-2 Allowed Values for Diagnostic Output Specification String

Entry Allowed for Key Description Entries Allowed for Value
type The type of output. file, channel
This key must be used first when specifying The default value (if the type key is
diagnostic output. not specified) is file.
name The name of the output file or channel. filename, stdout, console
This key must be used second when specifying filename may be absolute or
diagnostic output. relative.
batchsize The number of message events that are sent number
before an acknowledgement is requested from
the Communicator Server.
The batchsize key is only enabled if the type
key is set to channel.
maxsize Maximum size (in bytes) of the output file number
before it rolls over. Suffix the number with a k to
The maxsize key is only enabled if the type indicate kilobytes, or an m to
key is set to file. indicate megabytes.
For example, 2000k and 2m
specify 2 megabyte maximum size.
The default value is 100KB.
numbackups The number of backups that are kept. Each number
output file rollover generates a new backup The default value is 1.
file.
The numbackups key is only enabled if the
type key is set to file.
flushaftermessage Boolean indicating whether output should be true, false
flushed to the output file after each message. The default value is true.
The flushaftermessage key is only enabled if
the type key is set to file.

Table B-2 Allowed Values for Diagnostic Output Specification String (Continued)
Entry Allowed for Key Description Entries Allowed for Value
binary Boolean indicating whether the output is true, false
binary (language neutral) or text (human The default value is false.
readable).
The binary key is only enabled if the type key
is set to file.
sourceprefix Boolean indicating whether diagnostic true, false
messages should be prefixed with their source The default value is true.
module identifier.
The sourceprefix key is only enabled if the
binary key is set to false and the type key
is set to file.
idprefix Boolean indicating whether diagnostic true, false
messages should be prefixed with their symbol The default value is false.
name.
The idprefix key is only enabled if the binary
key is set to false and the type key is set to
file.
timeprefix Boolean indicating whether diagnostic true, false
messages should be prefixed with their long The default value is false.
timestamp.
The timeprefix key is only enabled if the
is set to file.
shorttimeprefix Boolean indicating whether diagnostic true, false
messages should be prefixed with their short The default value is true.
timestamp.
The shorttimeprefix key is only enabled if the
is set to file.
categoryprefix Prints the category used to define the message. true, false
The default value is false.
threadprefix Prints the ID of the thread that created the true, false
message. The default value is false.
encoding Specifies the type of character encoding used. The default value is UTF-8.

EXAMPLE USAGE
The following are examples of how to set the diagnostic output specification:
! type=file, name=/temp/abc.txt, maxsize=1m,
sourceprefix=false
! type=file, name=/temp/abc.txt, max=1m, source=false
! type=channel, name=diagchans/chan1
! name=Program Files\Vitria\log\chanlog.bin,
numbackups=6, flushaftermessage=false,binary=true
! name=console
CONCATENATION
Output can be sent to multiple destinations by using the + sign to combine
specifications. For example:
type=channel, name=chanlist/mychan + type=file,
name=filelist/myfile


C C SCRIPTABLE BME
This appendix introduces the Scriptable BME, which is a command-line utility to

deploy a project, given sources extracted from a versioning system.
Note: In Unix, an X-server is required to run this command-line utility.
This appendix contains the following topics:

! Overview
! Scriptable BME Command File
! Scriptable BME Commands
OVERVIEW
During the development of a BusinessWare project, it is usually necessary to build
and deploy the project multiple times during testing and debugging. In addition,
there may be times when you must redeploy in a production environment. To
enhance the reliability and the reproducability of your deployments,
BusinessWare includes a command-line script that automates the build and
deployment process. The features and functions of this script are collectively
referred to as the Scriptable BME. The following sections describe how to
configure and use the Scriptable BME.
SCRIPTABLE BME COMMAND FILE

Table C-1 briefly lists the commands available using the Scriptable BME. These
commands are defined in a file that is specified when running the command-line
script. For example, to execute the Scriptable BME, you invoke the following
batch file from the command prompt:
bmescript.bat/sh commandfile
The commandfile specifies the file in which the commands are defined for your
specific deployment. It is interpreted line by line. Blank lines and lines beginning
with a semicolon (;) or hash (#) are considered comments. Whitespace is ignored,
and double quotes can be used to deliminate strings containing spaces.
BusinessWare Modeling Guide C-1

SCRIPTABLE BME
Scriptable BME Command File
Each command should adhere to the following format:

Command [[parameter=value]*]
For example:
# open the RFQSample project at the specified location
openproject name=RFQSample
location=$VITRIA/scriptable/project
MapImportMountPoint="$VITRIA/samples/modeling/RFQSampl
e/project=$VITRIA/scriptable/project"
# deploy the project
deployproject todirectoryserver=true
# export the project to $VITRIA/test.jar
exportproject location=$VITRIA/test.jar
The contents of the command file are validated before it is executed, and any
unrecognized command or parameter terminates the processing of the file. If
terminated, a non-zero error code is displayed in the command window that
invoked the script. Progress and warning messages are also displayed in the
command window. After successful completion of all the listed commands, the
script returns error code zero.
Table C-1 Scriptable BME Commands

Command Description parameters
OpenProject Creates and activates a new Name
project with a specified name Location
at a specified location. If a Import
.project file with the Mountpoint
name of the project exists at
the specified location. Export
Mountpoint
DeployProject Deploys the currently active ToFile
project. ToDirectoryServer
BuildFirst
Overwrite
InstallModule
ExportProject Exports the currently active Location
project.
InstallProjectModule Installs the specified project Location
so that it can be used as a
dependency by other
projects.
C-2 BusinessWare Modeling Guide

PART VIII: APPENDICES SCRIPTABLE BME
Scriptable BME Commands
SCRIPTABLE BME COMMANDS

As described in the section Scriptable BME Command File on page C-1, the
commands that dictate how and where your project is built and deployed are
specified in the command file. The following sections describe these commands
in more detail and provide examples of how to use the commands.
OpenProject
The OpenProject command creates and activates a new project specified by
parameters listed in the command file. If a project file already exists in the
specified location, the existing project properties (for example, project settings,
project parameters, mountpoints, and services) are applied to the new project.
The OpenProject command must specify values for the following two required
parameters:
! Namethe name of the the new project
! Locationthe location of the new project directory
For example, if the name of the project is myproject and the location is
F:/common/projects/myproject, at the command prompt, you would enter the
following:
OpenProject name=myproject
location=F:/common/projects/myproject
In addition to the two required parameters, you can also specify the following
optional parameter:
! MapImportMountPointoptional. Maps the current import mountpoints
to the supplied one. Multiple mountpoint maps can be specified separated by
commas. The option value must be enclosed in double quotes.
This is used to map a current import mount point to a new one. Typically, the
import mountpoint specified in a project is expanded and used when a project
import is done on a project jar. The import mountpoint is used by the scriptable
BME to set the mountpoints of a project when an OpenProject command is
invoked on a location that already contains a project. For example, suppose the
mountpoints in the .project file of an existing project is:
Export mountpoint Import mountpoint

F:/jedi/projects/foo $VITRIA/projects/foo

SCRIPTABLE BME
If a Project > New is done using BME, the import mountpoint will be
expanded and presented to be edited in the mountpoint dialog where the
mountpoint settings are shown as follows, assuming $VITRIA expands to
C:/jedi/export.
Export mountpoint Import mountpoint

$VITRIA/projects/foo C:/jedi/export/projects/foo
Using the BME, this can be fixed to be the correct mountpoint; for example,
C:/jedi/export can be modified to F:/jedi. But if OpenProject is
invoked in the same directory using scriptable BME, it will fail because the
user cannot modify the project mountpoint using a dialog.
To overcome this problem, the option MapImportMountPoint can be used
as follows:
OpenProject name=foo location=F:/jedi/projects/foo
MapImportMountPoint=$VITRIA/projects/foo=
F:/jedi/projects/foo
If the current Import Mountpoint in the .project file is
$VITRIA/projects/foo, then it will be replaced by
F:/jedi/projects/foo, and this is expanded. You could specify
$WS/projects/foo instead of F:/jedi/projects/foo and
bmescript will use the resolved result; for example,
F:/jedi/projects/foo if $WS resolves to F:/jedi, as the import
mountpoint.
Note: The location value and the import mountpoint value when the
import mountpoint represents the project root directory has to be the
same. In the above example, the location is F:/jedi/projects/foo.
If you have also mounted Z: pointing to F:/jedi/ and you specify the
import mountpoint map as
MapImportMountPoint=$VITRIA/projects/foo=
Z:/projects/foo, the new project infrastructure will mount the
directory specified by location option as the project root directory, which
is F:/jedi/projects/foo, and then will also mount
Z:/projects/foo since it does not know that Z points to F:/jedi.
You will have the same directory mounted twice which may result in
errors during your build.
DeployProject
The DeployProject command deploys the currently active project.
You can specify the following optional parameters:

PART VIII: APPENDICES SCRIPTABLE BME
! ToFilespecify the value false to suppress the creation of the deployed

project file. The default is true.
! ToDirectoryServerspecify the value true to deploy the directory
server specified by vtparams. The default is false.
! BuildFirstspecify the value false to build the project completely
from scratch without reusing existing objects present on the disk. This forces
a build, not just a compile. The default is false.
! Overwritespecify the value false to retain the existing deployed
resources, such as channels and servers, when deploying to the directory
server. The default is true.
! InstallModulespecifies installing the generated project file as a project
module within BME to allow it to be used as a dependent project. Only valid
if toFile is true. The default is false.
ExportProject
The ExportProject command exports the currently active project.
You can specify the following optional parameter:

! Locationthe name and location of the file to contain the exported project.
Default, as computed by BME (project directory..\ProjectName.jar)
InstallProjectModule
The InstallPorjectModule command installs the specified project so that it
can be used as a dependency by other projects.
The InstallProjectModule command must specify values for the following

required parameter:
! Locationthe name and location of the deployed project file that should be
installed as a Project Module and replaces any existing module.

SCRIPTABLE BME

INDEX
Symbols certificates 4-26

authority 4-26
.dat 2-13, 9-1, 9-2, 9-3, 9-4, 9-5 certificates authority 4-26
.wal 2-13, 9-2, 9-4 Chancheck 10-2
command-line tools 1-2
A Communicator Server 1-1
communicator server
access control system files A-5
administering 4-16 Communicator Servers
access levels 4-11 expert properties 2-13
adding BusinessWare administrators 4-22 multicast properties 2-11
administering properties 2-10
databases 5-1 trace levels 2-12
administration 1-5 connection
administration tasks 1-5 handshake 4-27
handshakes 4-27
hardened 4-27
B connector state 5-4
back up connectors
frequency 9-1 transaction ID map 5-4
runtime environment 9-3 credentials 4-26
what to backup 9-2 guest set up 4-21
backup SSL 4-28
directory server file 9-2
files to backup 9-2
operations 9-4 D
backup and restore files 9-1 data file A-5
bad magic number 9-5 databases
BPO table names 5-2 administering 5-1
BPOs 5-3 default security settings 4-19
BusinessWare deployment 1-4
administrators, adding 4-22 tasks 1-4
introduction 1-1 diagnostic file A-5
BusinessWare server 1-1, 2-7, 2-8 diagnostic loggers
properties 2-7, 2-8 binary file logger 2-20
system files A-5 text file logger 2-20
directory server 1-1
backup files 9-2
C installed items 1-4
cache permissions 4-19 permissions 4-16
caching permissions 4-19
BusinessWare Administration Guide Index-1

INDEX
E public-key encryption 4-26

encryption 4-26
keys 4-26 R
encryption keys 4-26 raw TCP 4-27
environment variables A-1 registry items A-1
VTPARAMS
relational database management system 1-1
.vtparams file A-2
names and default values A-3 required permissions 4-19
syntax A-2 restoring
VTPARAMS A-1 Chancheck utility 9-5
files 9-4
runtime environment backup 9-3
F
federation of servers 8-1 S
federation with BusinessWare 3.x channel 8-4
security 4-1
access control 4-16
H certificate and certificate authorities 4-26
connection handshakes 4-27
hardened connections 4-27 credential 4-26
default settings 4-19
I encryption 4-26
encryption keys 4-26
installation 1-3 hardened connections 4-27
integration server 1-1 LDAP over SSL 4-32
connection manager settings 2-19 options 4-27
trace levels 2-19 principal 4-25
transaction manager settings 2-19 raw TCP 4-27
SSL 4-28
SSL, configuring 4-30
J TCP 4-27
Java servlet engine 1-1 terminology 4-25
security and access control 4-22
servers
L BusinessWare server 1-1, 2-7, 2-8
LDAP over SSL 4-32 Communicator Server 1-1
directory server 1-1
log files B-1
federation 8-1
integration server 1-1
M Java servlet engine 1-1
relational database management system 1-1
management tools 1-2 web server 1-1
command-line tools 1-2 SSL 4-28, 4-30
vtadmin 1-2 connection handshake 4-27
Web Administration Tool 1-2 credentials 4-28
hardened connections 4-27
P security options 4-27
supported ciphers 4-29
permissions 4-16 terminology 4-25
required 4-19 state
principal 4-25 connector 5-4
Index-2 BusinessWare Administration Guide

INDEX
transaction manager 5-3 access levels 4-11

subsystems 1-1 creating 4-12
symmetric encryption 4-26 rights 4-11
system files A-5 utilities
vtadmin 3-1
T
V
table names for BPOs 5-2
tables, timer 5-4 vtadmin 1-2, 3-1
tasks and activities of workflow 5-4
TCO 4-27 W
timer tables 5-4
transaction ID map 5-4 Web Administration Tool 1-2, 2-1
transaction manager state 5-3 Web servers 1-1
troubleshooting and tips 11-1 workflow
tasks and activities 5-4
write-ahead log file A-5
U
users and groups
BusinessWare Administration Guide Index-3

INDEX
Index-4 BusinessWare Administration Guide

BusinessWare Administration Guide 4.2.1

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

BusinessWare Administration Guide 4.2.1

Hochgeladen von

Copyright:

Verfügbare Formate

BusinessWare

Vitria, BusinessWare, Vitria Collaborative Application, VCA, VCML,

This document, as well as the software documented in it, is furnished

Chapter 1 Introduction to BusinessWare Administration. . . . . . . . 1-1

Chapter 2 Using the Web Administration Tool . . . . . . . . . . . . . . . . 2-1

BusinessWare Administration Guide iii

All Projects View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Chapter 3 Using the Command-Line Administration Tool . . . . . . . 3-1

Chapter 4 Security and User Management. . . . . . . . . . . . . . . . . . . . 4-1

iv BusinessWare Administration Guide

Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Chapter 5 Administering Databases . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

BusinessWare Administration Guide v

Increasing Buffer Pool and Table Space . . . . . . . . . . . . . . . . . . . . . 5-6

Chapter 6 Administering Web Servers . . . . . . . . . . . . . . . . . . . . . . . 6-1

Chapter 7 Administering Business Cockpit . . . . . . . . . . . . . . . . . . . 7-1

Chapter 8 Interoperability with BusinessWare 3.x Installations . . 8-1

vi BusinessWare Administration Guide

Chapter 9 Backing Up and Restoring Files . . . . . . . . . . . . . . . . . . . 9-1

Chapter 10 Command-Line Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

BusinessWare Administration Guide vii

Chapter 11 Troubleshooting and Tips . . . . . . . . . . . . . . . . . . . . . . . 11-1

Appendix A Environment Variables, Registry Items, and System Files .

Appendix B BusinessWare Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . B-1

viii BusinessWare Administration Guide

Appendix C Scriptable BME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

BusinessWare Administration Guide ix

x BusinessWare Administration Guide

Welcome to the BusinessWare Administration Guide.

This preface contains the following information:

BusinessWare Administration Guide xi

BUSINESSWARE DOCUMENTATION SET

Table 1 BusinessWare Documentation

xii BusinessWare Administration Guide

Table 1 BusinessWare Documentation (Continued)

BusinessWare Administration Guide xiii

Table 1 BusinessWare Documentation (Continued)

HOW THIS GUIDE IS ORGANIZED

Table 2 Contents of this Guide

xiv BusinessWare Administration Guide

Table 2 Contents of this Guide (Continued)

BusinessWare Administration Guide xv

COMMAND-LINE NOTATION CONVENTIONS

xvi BusinessWare Administration Guide

We would like to hear from you.

BusinessWare Administration Guide xvii

xviii BusinessWare Administration Guide

The BusinessWare Administration Guide provides the necessary information to

BusinessWare Administration Guide 1-1

! Directory Serverserver that provides a central repository for all runtime

WEB ADMINISTRATION TOOL

COMMAND-LINE TOOLS (UTILITIES)

1-2 BusinessWare Administration Guide

INSTALLATION, DEPLOYMENT, AND ADMINISTRATION

BusinessWare Administration Guide 1-3

! Various areas of BusinessWare, such as multiple server pairs

Directory Server-Related Items

For more information on installation, see the BusinessWare Installation Guide.

The BusinessWare Modeling Environment provides a Deployment Tool that

Deployment activities include:

1-4 BusinessWare Administration Guide

" Partitioning the components across the server environment

For more information on deployment, see the BusinessWare Modeling Guide.

For more information on administration, access the BusinessWare Administration