TIBCO Business Works - Process Design Guide - Nov 2002

TIBCO BusinessWorks™

Process Design GuideSoftware Release 2.0.0November 2002

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE TIBCO BUSINESSWORKS CONCEPTS). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

Technologies described herein are covered by existing patents and pending patent applications. TIBCO technology is protected under US patent number 6,003,011.

TIB, TIBCO, Information Bus, The Power of Now, TIBCO Rendezvous, TIBCO AlertServer, TIBCO Adapter SDK, TIBCO AdapterAdministrator, TIBCO Repository, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

Copyright © 2001-2002 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTIBCO BusinessWorks Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOther Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1 Overview of TIBCO Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Starting TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Startup Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

TIBCO Designer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Project Tree Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Palette Panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Design Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Configuration Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Customizing the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Choosing Palette Panel Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Choosing Palette Mode or Category Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Displaying Palettes in a Separate Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Selecting the Palettes to Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Working With Custom Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2 Managing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Overview of Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Save Project Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Project Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Project Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Creating Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Saving Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Saving a Project as a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

TIBCO BusinessWorks Process Design Guide

iv | Contents

Storage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Local File Projects and Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using Project Backups (Maintenance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Keeping Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Restoring from Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Customizing Maintenance Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Opening Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Importing a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Working With Resources in Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25If Adding a Resource Results in an Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Importing or Exporting a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Working With Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Business Process Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32TIBCO BusinessWorks Solves Enterprise Integration Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Overview of Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Process Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Shared Configuration Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Subprocesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Developing Process Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 4 Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Activity Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Activity Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Advanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Process Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Mapping and Transforming Activity Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Process Starters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Start Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58


Contents | v

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Output Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

End Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Output Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Error Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Chapter 5 Transitions and Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Creating a Transition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 6 Grouping Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Overview of Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

No Action Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Transaction Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Overview of Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Index Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Accumulate Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Iterate Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Repeat Until True Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Repeat On Error Until True Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Suspend If Still Error Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 7 Mapping and Transforming Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Overview of Mapping and Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Icons on the Input Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Specifying Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Date and Datetime Strings in Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Mapping Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Evaluation Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Effects of Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Simple Element to Simple Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Branch to Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Non-Repeating to Repeating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Repeating to Non-Repeating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Repeating to Repeating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Mappings That Are Not Useful . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96


vi | Contents

Transforming Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Modify Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97If Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Choose Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99List Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Copy-Of and Copy-Contents-Of. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Set Substitution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 8 XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

XPath Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Addressing Schema Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Evaluation Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Search Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

The XPath Formula Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Chapter 9 Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Overview of Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

The $_error Process Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Error Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Group Error Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Called Process Error Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Process Error Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 10 Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Overview of Inter-Process Communication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Data for Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Coordinating Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Specifying the Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Timeouts for Notify and Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Database Storage for Wait/Notify/Receive Notification Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Examples of Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Enforcing Order for Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Multiple Types of Incoming Events Resume a Running Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Scalability With Incoming Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Specific Protocol Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Chapter 11 Testing Process Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Overview of Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131


Contents | vii

The Test Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Process Instances During Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Creating Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Working With Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Stepping Through a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Colors in Test Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Test Mode Buttons and Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Chapter 12 Implementing a Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Overview of Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Deployment Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Creating a Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Sending a Deployment Configuration to the TRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Starting Deployment Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Undeploying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Controlling Execution of Process Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Process Instances and System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Specifying Maximum Number of Concurrent Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Keeping Process Instances in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Configuring Storage for Process Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Database Table Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Configuring Fault-Tolerant Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Peer or Master and Secondary Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Failover and Checkpoint Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Process Starters and Fault-Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Appendix A Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159


viii | Contents


| ix

Figures

Figure 1 TIBCO Designer startup window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Figure 2 The TIBCO Designer window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 3 The project tree panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Figure 4 Resources in project tree and design panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Figure 5 Palette panel changed depending on current selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Figure 6 The three-panel view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 7 Category mode vs. palette mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Figure 8 Adding a resource to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Figure 9 An example enterprise computing environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 10 A business process flow of an example enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Figure 11 A process engine creating process instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Figure 12 A newly created process definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 13 A main process calling a subprocess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Figure 14 Developing process definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Figure 15 Valid transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Figure 16 An invalid transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Figure 17 The condition dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Figure 18 Mapping activity input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Figure 19 The XPath formula builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Figure 20 Creating an XPath formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Figure 21 A simple error-handling procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Figure 22 Propagating errors from a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Figure 23 Propagating errors from a called process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Figure 24 The Error Schemas tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Figure 25 The Generate Error Configuration tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Figure 26 Example of process data for error schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Figure 27 Ordering incoming events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Figure 28 Multiple event sources to continue a process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127


x | Figures

Figure 29 Set breakpoints dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Figure 30 Setting a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Figure 31 Process instance stopped at a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Figure 32 The test window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Figure 33 Multiple process instances in the test window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Figure 34 Sample deployment configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Figure 35 Relationship between deployment resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Figure 36 Normal operation: master processing while secondary stands by . . . . . . . . . . . . . . . . . . . . . . . . 152

Figure 37 Fault-tolerant failover. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153


| xi

Tables

Table 1 Options when starting TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Table 2 Example activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Table 3 Activity icon elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Table 4 Activities with Event tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Table 5 Datatypes for schema items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Table 6 Process starters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Table 7 Group configuration tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Table 8 Input tab buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Table 9 Icons for schema items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Table 10 Additional icons for items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Table 11 Mapping simple elements and branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Table 12 Mapping repeating and non-repeating items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Table 13 XPath formula builder elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Table 14 Colors in test mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Table 15 Toolbar icons for testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Table 16 Test window icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137


xii | Tables


| xiii

Preface

TIBCO BusinessWorks is a standards-based, easy-to-deploy solution for companies looking to integrate their enterprise computing environment and automate their business processes. This manual describes how to create process definitions using TIBCO BusinessWorks.

Topics

• Related Documentation, page xiv

• How to Contact TIBCO Customer Support, page xv


xiv | Preface

Related Documentation

You may find the following documentation resources useful.

TIBCO BusinessWorks DocumentationIn addition to this manual, the following documents are part of the TIBCO BusinessWorks documentation set:

• TIBCO BusinessWorks Concepts Read this manual before reading any other manual in the documentation set. This manual describes terminology and concepts of TIBCO BusinessWorks, and the other manuals in the documentation set assume you are familiar with the information in this manual.

• TIBCO BusinessWorks Quick Start This manual steps you through a very simple example of designing, deploying, and monitoring a TIBCO BusinessWorks process.

• TIBCO BusinessWorks Business Palette Reference This manual describes each of the palettes available in TIBCO BusinessWorks.

• TIBCO BusinessWorks Installation Read this manual for information on installing one or more components of TIBCO BusinessWorks and setting up a TIBCO BusinessWorks domain.

• TIBCO BusinessWorks Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closes issues for this release.

Other DocumentationTIBCO BusinessWorks is bundled with other products. You will therefore find the documentation for those products useful:

• TIBCO Designer documentation. TIBCO Designer is an easy to use graphical user interface for design-time configuration of TIBCO applications. TIBCO Designer includes online help for each palette.

• TIBCO Administrator documentation. TIBCO Administrator is the monitoring and managing interface for new-generation TIBCO products such as TIBCO BusinessWorks.

• TIBCO Adapter product documentation


How to Contact TIBCO Customer Support | xv

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Product Support at:

http://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one. You must have a valid maintenance or support contract to use this site.


xvi | Preface


| 1

Chapter 1 Overview of TIBCO Designer

TIBCO Designer is an easy to use graphical user interface for creating and deploying integration projects. TIBCO Designer allows you to easily drag and drop components into a project and then specify configuration information for each component.

This chapter and the next give an introduction to TIBCO Designer and working with projects. If you are unfamiliar with TIBCO Designer, these chapters introduce you to the basic concepts needed before attempting to create automated business process definitions.

Topics

• Starting TIBCO Designer, page 2

• TIBCO Designer Interface, page 4

• Customizing the Display, page 8


2 | Chapter 1 Overview of TIBCO Designer

Starting TIBCO Designer

How to start TIBCO Designer depends upon the platform you are using. The following sections describe how to start TIBCO Designer and explains the options available once TIBCO Designer starts.

Starting the ProgramStart TIBCO Designer using the following steps:

Windows 1. Click Start>Programs>Tibco>product_name>Designer

where product_name is the name of the product, such as TIBCO BusinessWorks 2.0 or TIBCO Adapter for Files 4.2.

2. Select one of the Startup Options. See Startup Options on page 2.

UNIX 1. Navigate to the Designer/bin directory.

2. Type ./designer

3. Select one of the Startup Options. See Startup Options on page 2.

Startup OptionsWhen you launch TIBCO Designer, the startup window is displayed. Figure 1 illustrates the startup window.

Figure 1 TIBCO Designer startup window


Starting TIBCO Designer | 3

Table 1 describes the startup options.

Table 1 Options when starting TIBCO Designer

Option Description

New empty project

Opens a new empty project in TIBCO BusinessWorks. An empty project includes

• Root folder displayed in the project tree panel.

• Schemas folder displayed in the project tree and the design panel. Most schema resources are automatically created during configuration. Advanced users define schema using the resources in that folder.

By default when you open a new project, you are prompted for the location where you want to save it. You may provide the location or click the Cancel button. Use Edit>Preferences>General and turn off Show save dialog for new project, if you do not want to see this dialog when creating new projects.

New project from template

Opens a predefined project template. A project template is a pre-built project. It can contain folders, configured resources, and partially configured resources.

A project template can be preconfigured to include all the resources you may need for your project. Using a template, you can leverage your work when performing similar configurations.

To create a project template, save your project as a template. See Saving a Project as a Template on page 19.

Open existing project

Opens an existing project. See Opening Projects on page 22.

Maintain a project

Allows you to choose a previously save project and restore backed up versions or set backup options. See Using Project Backups (Maintenance) on page 20 for more information.

Root folderSchemas folder



TIBCO Designer Interface

The TIBCO Designer interface allows you to perform various functions. This section describes the TIBCO Designer main window and explains what you see in each of its panels.

Help Displays TIBCO BusinessWorks documentation. You may be prompted for your browser if you are using TIBCO BusinessWorks for the first time. Click Help in the dialog to display the location in which browsers are installed by default.

Exit Exits TIBCO BusinessWorks. If there are unsaved projects, you are prompted to save them.

Show this panel only on startup

If checked, the panel is only displayed during startup and closed after you’ve made your selection.

If unchecked, this panel reappears when no other TIBCO BusinessWorks windows are open. Leaving the panel on screen is useful for project maintenance.

Table 1 Options when starting TIBCO Designer

Option Description


TIBCO Designer Interface | 5

Main WindowFigure 2 illustrates the TIBCO Designer main window.

Figure 2 The TIBCO Designer window

The TIBCO Designer window has these components:

• Menu bar and Menus.

• Toolbar icons.

• Four panels, which are (starting in the top left corner and continuing clockwise):

— Project tree panel

— Design panel

— Configuration panel

— Palette panel

You can rearrange the panels. See Customizing the Display on page 8.

The following sections explain the contents of each panel.

Design panel

Configurationpanel

Menu bar

Toolbar

Palette

Project treepanel

panel

When you first start TIBCO Designer on a machine, it displays its default view. You can then customize your display. Customization is saved and remains in effect, even if you uninstall the product and install a different minor version.



Project Tree Panel A project contains objects called resources that implement the enterprise integration. This includes services (producers and consumers of information), any business logic that may be applied to that information, and deployment information.

Each TIBCO Designer window contains one and only one project, which is represented as the root folder in the window.

Figure 3 illustrates an example project, ProcessNewComputer, in the project tree panel. Multiple TIBCO products were used to create the integration project: it contains two Process Definitions (ProcessOrder and ProcessSoap) and a Siebel adapter (SBLAccount).

Figure 3 The project tree panel

Resources

Resources are the components of a project. A simple TIBCO Designer resource corresponds to an object in a TIBCO application, such as an adapter configuration, an adapter service, a process definition, or an FTP activity. The illustration below shows the resources of the ProcessNewComputer project in both the project tree and the design panel.

Figure 4 Resources in project tree and design panel

ProcessNewComputer project

Resourcesin project tree

Resourcesin design panel


TIBCO Designer Interface | 7

Resources can be complex and contain other resources, much like a folder can contain other folders on your computer’s file system. For example, an adapter configuration may contain multiple folders with multiple publisher or subscriber service resources.

Most resources have context-sensitive help available for the configuration of that resource. Right-click on the resource and choose What Is This? from the popup menu for more information on configuring the resource.

Palette Panel Palettes organize resources and allow you to add them into your project. You select resources in the palette panel and drag-and-drop them into the design panel to add them to your project.

TIBCO BusinessWorks contains a small number of native palettes. In addition, each TIBCO application you install adds one or more palettes during installation.

Which palette is displayed depends on the resource selected in the project tree and on your preferences (See Customizing the Display on page 8). In the default view, the current selection in the project tree determines which palettes are displayed in the palette panel.

Figure 5 Palette panel changed depending on current selection

For example:

• Select the root folder to see a palette for each installed adapter and some other palettes for general resources.

• Select the Adapter Services folder of an adapter in the project tree to see a palette of service resources. Drag any service resource into the design panel to add that resource to that adapter.

Root folder selected Adapter Services folder selected



• Select a Deployment Configuration resource in the project tree to see the resources available for deployment.

Design PanelThe design panel displays the current resource selected in the project tree panel. For resources that contain other resources, the contents of the selected resource are shown in the design panel. For example, if you select a folder, its contents is displayed.

Configuration PanelThe configuration panel allows you to specify configuration options for the selected resource. The type and the purpose of the resource determine the contents of the configuration panel. There are usually one or more tabs in the configuration panel that allow you to access the various configuration options. The tabs provide an organization to the options for the resource.

You can click the question mark icon (?) in the top right corner of the configuration panel for online help on the current selection.

For each tab, you must click Apply after you have specified configuration information before you can select another tab. If you decide you do not want to add the configuration information, click Reset before you apply any changes to return to the previous values for each field in the tab.

Customizing the Display

User preferences determine how TIBCO Designer displays palettes and the panels. You can also add custom palettes to TIBCO Designer. This section gives an overview of the most frequently used custom preferences.


Customizing the Display | 9

Display preferences and other preferences are saved when you exit TIBCO Designer, even if you do not save your project.

Choosing Palette Panel LocationIf you prefer to view either the project tree or the palette panel, but not both in the left panel, you can set TIBCO Designer to display the three panel view, illustrated in Figure 6.

Figure 6 The three-panel view

To choose the three-panel view, follow these steps:

1. Choose Edit>Preferences>View.

2. Under Layout, select the left icon and click OK.

To return to Designer default settings, remove the preference file, which can be found in the following locations:

• Windows 2000: C:\Documents and Settings\<userid>\.TIBCO

• Windows NT: C:\Winnt\Profiles\<userid>\.TIBCO

• UNIX systems: On the systems, the Designer.prefs file is created in the .TIBCO directory in the user’s home directory by default. Note that .TIBCO is a hidden directory; you need to use ls -a to see it.

Projectpanel

Configurationpanel

Designpanel



To navigate to palettes in this view, click the Palettes tab. The next diagram shows the results of this action.

Choosing Palette Mode or Category ModeBy default, only resources that you can use in the current context are displayed in the palette panel. This default mode is known as category mode. You can change to palette mode to display all palettes and their resources. Resources you cannot use for the current selection are grayed out for each palette.

Figure 7 illustrates the palette panel in category mode and palette mode.

Select Palettes

While in palette mode, you can close individual palettes using the Close button on the right.

To redisplay a closed palette, choose Edit > Preferences > Palettes, then select the palette and, in the bottom panel, the categories for which it should be displayed.

If you do not see Close buttons, choose Edit > Preferences > Palettes, then select Show Close Buttons on Palettes.



Figure 7 Category mode vs. palette mode

Choose one of the following methods to switch between category mode and palette mode:

• Choose Edit>Preferences>Palettes, then select or unselect the Show Category Palettes checkbox and click OK.

• Click the Switch Palette Modes button located in the tool bar.

Displaying Palettes in a Separate WindowYou can display the palette panel in a separate window by choosing Window > Show Palettes in Separate Window. You can also access this menu command from the right-button menu of any resource in the palette panel.

To restore the palette panel to its location in the main window, close the separate window in which the palette panel is displayed.

Category mode Palette mode

Only currently usable resources display

All resources display in each palette

Close button

Switch Palette Modes



Selecting the Palettes to DisplayYou can restrict which palettes (or resources) appear by modifying the palette preference. To change which palettes are displayed choose Edit > Preferences > Palettes. A Palette Preferences dialog shows palettes for all installed applications and allows you to choose which palettes should be displayed.

Select a palette, then click to select or unselect a resource category. If you unselect all resource categories for a palette, the palette (or resources from that palette) does not display in TIBCO Designer.

Working With Custom PalettesYou can create a custom palette so you can save a certain collection of resources to a predefined location and either share it with other users or use it yourself at a later time.

To add a custom palette, follow these steps:

1. Choose Project>New Custom Palette.

2. Save the palette either to your own directory or as part of the project.

3. Drag resources from the project tree or from the design panel into the customer palette.

4. When you save your project, the custom palette is then saved to the appropriate location.

Selectpalette

Select or unselectresource category



Deleting Custom Palettes

If you want to delete a custom palette, you must use your file system to locate and remove the palette. To find where custom palettes are located, select Edit>Preferences>General from the TIBCO Designer menu. On the resulting dialog, the User Palette Directory field specifies the location of custom palettes.




| 15

Chapter 2 Managing Projects

Projects are the key organizational principle for the configuration information you specify with TIBCO BusinessWorks.

This chapter explains how to create, open, and save projects. It also discusses how to use the project maintenance facility for backups.

Topics

• Overview of Projects, page 16

• Creating Projects, page 16

• Saving Projects, page 18

• Using Project Backups (Maintenance), page 20

• Opening Projects, page 22

• Importing a Project, page 24

• Working With Resources in Your Project, page 25

• Working With Global Variables, page 27

It is not possible to have multiple projects open at the same time. You therefore create new projects and open projects from the startup window.


16 | Chapter 2 Managing Projects

Overview of Projects

A project is a collection of all configured resources, including adapter resources, process definitions, and deployment configurations. Together, these resources make up your integration project. In the TIBCO BusinessWorks window, a project is represented by the top-level (root) folder in the project tree panel. The top-level folder is initially named Untitled and is renamed to the name of the project when you save the project for the first time.

When you close a project, the startup window remains available for project maintenance or opening for opening a different project unless you selected the Display this window only on startup check box on that window.

Save Project OptionsYou can save a project as a local file or a server-based project. You can also save a project as a project template.

Project TemplatesA project template is a pre-built project. It can contain folders for organization, configured resources, and partially configured resources. You can use a project template as the foundation for other projects similar in nature. Using a template you can leverage your work when performing similar configurations.

Project MaintenanceWhen you save a project for the first time, you are prompted whether you want to keep backups. See Using Project Backups (Maintenance) on page 20 for more information on backups.

Creating Projects

You create a new project using the startup window when starting TIBCO BusinessWorks. Also, if you did not select the Display this window only on startup check box in the startup window, you may close the current project to return to the startup window and create a new project.


Creating Projects | 17

TIBCO BusinessWorks allows you to create a project from scratch or to create a template-based project.

• New Project — A new project contains a single Schemas folder that will be used for schema resources.

• Project from Template — When you save a project as a template (Project > Save As Template), you can later use that template to create a new project.

To create a new project, follow these steps:

1. Launch TIBCO BusinessWorks.

2. When the startup window is displayed, choose either New empty project or New project from a template.

3. Provide template information if needed.

4. In the Save Project dialog that displays on top of the main window, click New Project.

5. In the Create Project dialog that appears, supply the appropriate information about the project and click Create.

6. In the Save Project dialog, click OK.

To save a server-based project, you must have full access privileges for the domain. Users with administration privileges can perform user management, including assigning full access privileges, using the TIBCO Administrator GUI.

For server-based projects, the user specified in the Create Project dialog must have full access privileges for that domain to create a new project.



Saving Projects

To save a project, follow these steps:

1. In the main window, do one of the following:

— Choose Project>Save.

— Choose Project>Save As>Local File or Project>Save As>Server-based Project.

— Press Ctrl-S.

— Click the Save icon.

You are also prompted whether you want to save a project when you launch TIBCO BusinessWorks with a new empty project.

2. The Save Project window appears with the following tabs:

If you used the Project>Save As menu, the tab corresponding to the menu item you chose is selected.

3. Next, the Backup? prompt lets you choose to keep backups of your project.

— If you click Yes, TIBCO Designer keeps incremental backups of your project. Each time you save a project, you are prompted for a label. TIBCO BusinessWorks then keeps backups of the differences between versions of the project. You can restore from any label you choose, as long as the maximum storage limit has not been exceeded. See Customizing Maintenance Settings on page 22

— If you click No, TIBCO BusinessWorks does not keep incremental backups and does not prompt you for a label. If you later decide to keep backups, supply a size for the project in the Project Maintenance dialog available by way of the Maintain a Project option from the startup window.

Local File Saves the project as a local file. If the project already exists, you may overwrite it. Otherwise, click New Project to create a new project file and save the information there.

Server-based

Project Saves the project as a server-based project. If the instance already exists, you may overwrite it. Otherwise, click New Project to create a new project and save the information there.

Note: The user specified in the New Project dialog must have full access privileges for the domain to save a project.


Saving Projects | 19

Saving a Project as a TemplateTo save a project as a template, follow these steps:

1. Choose Project>Save As Template.

2. Provide the appropriate storage information, as discussed in Storage Tab on page 19.

Storage TabOnce you have saved a project, you can select the Storage tab to view and to copy/paste information about the project.

The following information is available:

Field Description

Instance Type Either remoteRv for server-based repositories or localFile for file-based projects.

Discovery Prefix (server-based)

TIBCO Rendezvous subject prefix for finding this project.

Directory (local) Directory in which this local file project is stored.

Project Name Name of this project.

Responsible Person

Owner of this project.

User Current user of this project.



Local File Projects and EncodingIf you are saving a project as a local file project, the project repository encoding is set to Latin-1. This encoding is more efficient than other encodings. However, if this encoding is used, all data that are sent using this encoding, even if the data is specified as UTF-8 (for example, Japanese characters). This results in data loss.

You can address this issue in two ways:

• Use server-based projects. The TIBCO Administration Server allows you to specify the encoding in the repo.encoding parameter of the file $TIBCO_HOME$\administrator\version\config\administrator.properties.

• Use the TIBCO Designer Repository Finder tool to change the encoding for the project to UTF-8. See the TIBCO Designer Repository Management Guide available via Help> Help For > Repository.

Using Project Backups (Maintenance)

The Maintain a project startup option allows you to create incremental backups, load them as needed, and set backup preferences.

Keeping BackupsTo keep backup copies of a project that has never been saved before, follow these steps:

1. After you exit the Save Project dialog, you are prompted whether you want to keep backup copies. Click Yes.

2. Each time you save a project, you are asked for a label of that version. Provide a label that helps you remember the state of the project later.

If you decide you no longer want to keep backups, set the Maximum Total Backup Size to 0. To access it, choose the Maintain a project option in the startup window.


Using Project Backups (Maintenance) | 21

Restoring from BackupYou can restore any backed up version of a project from the Project Maintenance dialog available by way of the Maintain a project option of the startup window. You must close all projects to restore a backup.

To restore a backed up version of a project, follow these steps:

1. Close your current project window to return to the startup window.

If Show this panel only on startup was selected, you must restart TIBCO BusinessWorks to display the startup window.

2. Choose Maintain a project

3. To select the project, click the Open Project button. See Opening Projects on page 22.

4. In the Project Maintenance dialog, select the backup you want to restore from the Current Backups pop-up.

5. Click Restore Project. A dialog informs you that when you select a backup, all later versions of the project (including the saved project) are altered and can no longer be used.

6. Click Yes if you are sure you want to proceed.

Unless there are problems, you are soon informed that restoring the backup was successful.

7. Click Open Project to open the restored backup.

When you restore a backup, all later versions of the project, including the most recently saved version, are altered and can no longer be opened in TIBCO Designer. Consider saving your project under a different name before you restore a backed up version.

The most recently saved project is not in the list of backups that you can restore. Instead, you can simply open that project. You select the backup from the list by the date/time it was saved. Once selected, the backup label is displayed.



Customizing Maintenance SettingsThe Maintain a Project dialog allows you to customize maintenance settings. To display this dialog, close all projects. The startup window is displayed unless you selected Show this panel only on startup. If you did, you have to restart Designer to display the startup window.

You can make the following changes:

• Turning on Backups. If no backups were selected for the project, TIBCO BusinessWorks sets the backup size to 0. To turn on backups, change backup size to an appropriate number, such as 1000 (kb).

• Turning off Backups. If backups were selected for the project, you can turn off backups by changing backup size to 0.

• Changing Backup Size. If you find you’re using too much or too little space for backups, change the size.

Opening Projects

You can open a project from the startup window when you launch TIBCO BusinessWorks. If TIBCO BusinessWorks is already open, close the existing project to return to the startup window. (If you selected the "Show this panel only on startup" check box in the startup window, you must restart TIBCO BusinessWorks to open a project.)

You can save the project to a local file or as a server-based project managed by a TIBCO Administration Server. When you open a project, you are therefore always given the option of opening a local file or a server-based project.

Increasing the size has no side effects, decreasing the size can remove backups to fit the new size, and decreasing to 0 removes all backups

You can open projects or other repository files. It is not required that the project was created in TIBCO Designer.


Opening Projects | 23

Local File

Allows you to open a project that has previously been saved in a file. A window prompts you for the user name and location of the file. Click Browse to select the file.

Server-based Project

Opens a server-based project. The server is a TIBCO Administration Server if you are using TIBCO Designer as part of TIBCO BusinessWorks, or a TIBCO Repository Server otherwise. If running TIBCO Designer in standalone mode, you may need to start the Repository Server explicitly.

A window prompts you for information. Click the Show Advanced button to show TIBCO Rendezvous connection parameters. Note that in most cases, the default is appropriate.

To open a server-based project, you must specify your user name and password. You can only open a project if you have appropriate permissions.

For projects that are created as part of TIBCO BusinessWorks, username and password are assigned using TIBCO Administrator.

You can click Load Project List to retrieve a list of projects using the current connection parameters.



Importing a Project

When you import a project into another project, you add all the resources in the imported project into the current project.

Field Description

User Name of the user who wants to access the project.

Password Password for that user.

Domain TIBCO Administration domain from which to load this project or TIBCO Repository Server which manages this project. Defaults to the current domain. Click Discover Domains for a pop-up of all currently available domains and servers using the specified (or default) TIBCO connection parameters.

Project Name Name of the project. Type in a name or click Load Project List to retrieve a list of projects in the domain (or managed by the server) specified above.

Show Advanced

Displays TIBCO connection parameters. Click this check box only if your project uses a non-default setup.

A TIBCO Administration Server (or TIBCO Repository Server) for a domain must be running if you want to access remote repositories.


Working With Resources in Your Project | 25

To import a project, choose Project>Import Project.

Importing projects is useful because it bypasses the export step when you want to combine projects.

Working With Resources in Your Project

Once you have started TIBCO Designer, you can add resources to your project. Adding resources involves finding the resource in the appropriate palette and dragging and dropping it into the design panel.

To add resources to your project:

1. Select the palette in which the resource can be found. For example, you find an adapter resource in the palette named after the adapter.

2. Select a resource within the palette and drag and release it in the design panel.

The resource instance is displayed in the design panel and also added to your project tree. The configuration panel allows you to specify configuration information for the resource.

Figure 8 illustrates adding a resource to a project.

You can also select the resource in the palette panel and choose Add This To The Project from the right-button menu.



Figure 8 Adding a resource to a project

If Adding a Resource Results in an ErrorWhether adding a resource is successful or not depends on what is currently displayed in the design panel. If you try to add a resource that cannot be added to the current resource displayed in the design panel, an error results.

For example, if the root folder is displayed in the design panel, you can add an adapter instance. If any other resource is displayed, you cannot add the adapter instance.

Importing or Exporting a ResourceYou can export a resource from a project and import that resource into a different project. This functionality is useful if you wish to share resources among people working on your integration project.

To export a resource, perform the following:

1. Select the resource in the project tree

Drag into design panel

Ideally, all resources that cannot be dragged into the design panel should be greyed out (palette mode) or not visible (resource mode). For some custom palettes that may not always be true.


Working With Global Variables | 27

2. Choose Resources>Export Resource.

3. Save the resource to a location of your choice. You may choose one of these formats:

— AE XML Format. The TIBCO ActiveEnterprise standard format. This is the format used by TIBCO Designer by default, and this is the recommended format for export.

— Repository XML Format. The TIBCO Repository format. This format is compatible with older ActiveEnterprise repositories

— Designer XML Format. A special TIBCO Designer XML format.

4. Transfer the file to the person who will import the resource.

To import a previously exported resource, perform the following:

1. Obtain a file containing an exported resource.

2. Select the appropriate location for the resource in the project tree.

3. Choose Resources>Import Resource.

4. Locate the file containing the previously exported resource. Use the Browse button to find the correct file.

Working With Global Variables

Global variables provide an easy way to set defaults for use throughout your integration project.

Be sure to choose the appropriate location for import. That is, you cannot import a resource into another resource that cannot accept the imported resource.

For example, you cannot import a Sessions Folder or a Publisher resource into a Sessions folder. You can only import Session resources and, optionally, their associated endpoints.

Note that if a resource with the same name as the imported resource already exists in the desired location, TIBCO Designer will not import the resource.

Once you have imported a resource, you can move the resource to a different location, if you desire.



For example, you could define a variable RvService and set its value to 7500. You can then assign the variable to different sessions in your adapter. If you wish to change the TIBCO Rendezvous service for your adapter, change only the global variable and you do not have to edit each individual session.

To use global variables in your project, follow these steps:

1. To define the variable, choose Edit>Global Variables.

The Global Variables window appears and displays the currently defined variables.

2. To create a new global variable

a. Choose a name.

b. Assign a value.

c. Click Set.

The window below illustrates the RvServiceTest variable assigned the value 7800.

The global variable is now displayed in the global variables list.


Working With Global Variables | 29

3. When you want to use the global variable in the fields of a resource, enter the variable name surrounded by %% on both sides. In the illustration below, the variable RvServiceTest is used as the service.

When the project is deployed and the configured components run, TIBCO BusinessWorks replaces all occurrences of the global variable name with the global variable value. For example, RvServiceTest would be replaced with 7800.

A number of global variables are predefined in TIBCO Designer. See Appendix A, Predefined Global Variables for information. You may add definitions of any variables you need to the predefined variables.




| 31

Chapter 3 Processes

TIBCO BusinessWorks allows you to graphically model your business processes and execute them automatically. This chapter describes how to create business processes within TIBCO BusinessWorks.

Topics

• Business Process Modeling, page 32

• Overview of Processes, page 34

• Process Definitions, page 35

• Activities, page 36

• Transitions, page 37

• Groups, page 38

• Shared Configuration Resources, page 38

• Developing Process Definitions, page 40


32 | Chapter 3 Processes

Business Process Modeling

Most businesses choose the best application or environment for processing each component of their core business. For example, in a typical enterprise, the flow of information and processing between each application is what drives the day-to-day operations of the business. For example, the order-entry application receives and processes orders based on availability information taken from the inventory system. The tracking system relies on order information and shipping information. Also, accurate and up-to-date reporting information is required from all systems.

Figure 9 illustrates an example enterprise computing environment with various systems running in different environments.

Figure 9 An example enterprise computing environment

Order Entry

Tracking

Inventory

Reporting

Shipping

Manual Data Transfer


Business Process Modeling | 33

Many companies implement the business rules that tie the systems together using custom-written code or by manual processes. Tying together different systems from different vendors that run in different environments is a labor-intensive and error-prone process that usually takes months of planning and implementation. Also, because the task of creating the custom business logic is so complex, businesses often rely on manual, paper-based processes instead of automating the process for greater efficiency.

Figure 10 illustrates a business process flow, sometimes known as a workflow, that describes the business rules between the various systems in an enterprise.

Figure 10 A business process flow of an example enterprise

The business process flow describes an integrated enterprise that contains order-entry, inventory, shipping, tracking, and reporting systems. Each of these systems have rules for processing incoming data and more rules for passing data between the systems. These rules are characterized by business processes, such as the REPORT SHIPPED ORDER STATUS process within the shipping system.

These business rules in themselves can involve complex processing and automating these processes is crucial to lowering the total cost of operating the complete enterprise environment.

TIBCO BusinessWorks Solves Enterprise Integration ProblemsAn ideal solution for handling business process automation would be a tool that can handle the different environments and applications and allow you to create programmatic business rules easily. That tool should also allow you to automate your business processes for the greatest efficiency.

Order Entry

IF available, THEN IF credit check approved, THEN IF priority order, THEN PROCESS ORDER ELSE HOLD ORDER ELSE DENY ORDERELSE RESTOCK INVENTORY

REPORT ORDER STATUS

Inventory

WHEN qty < 5 of prod_id 798 RESTOCK INVENTORY

PROCESS INVENTORY CHECK

REPORT INVENTORY STATUS

Shipping

WHEN orderIDStatus == complete SHIP ORDER

REPORT SHIPPED ORDER STATUS

Tracking

CHECK ORDER STATUS

CHECK INVENTORY ITEM STATUS

Reporting

GET SHIPPED ORDER FROG REPORT

GET INVENTORY REPORT

GET REVENUE REPORT

GET UNUSED INVENTORY REPORT



TIBCO BusinessWorks allows you to model business processes with a graphical tool. You can use the BusinessWorks process definition palette to diagram complex business logic easily. Once the business rules have been specified, BusinessWorks can execute the business processes, allowing you to easily automate the critical functions of your business.

BusinessWorks can help you specify the business logic and automate the processing of the interaction between the systems in your enterprise. This allows you to reduce the time to implement an integrated, enterprise-wide computing environment and ultimately lower the cost of deploying and maintaining the system.

Overview of Processes

A process definition is the graphical representation of your business process. You develop and test process definitions using TIBCO Designer. The process definition is executed by a TIBCO BusinessWorks process engine. A process engine creates instances of process definitions. These process instances automate your business processes by executing the business process described by the process definition.

Figure 11 illustrates the relationship between process definitions, a process engine, and process instances.


Process Definitions | 35

Figure 11 A process engine creating process instances

Process engines are started using TIBCO Administrator after you deploy your project. For more information about deploying a project, see the TIBCO BusinessWorks Administrator’s Guide.

The remainder of this book describes how to create the process definitions that eventually become running process instances.

Process Definitions

A process definition is a graphical representation of your business process model. You create process definitions by dragging and dropping a Process Definition resource from the Process palette to the design panel.

Selecting the process definition in the project panel changes the palette panel and the design panel to allow you to create your business process model. The palette panel contains a set of activity palettes for use in the process definition. The design panel displays the business process model. Newly created process definitions contain a Start activity and an End activity. Figure 12 illustrates a newly created process definition.

Machine A

TIBCO BusinessWorks Process Engine

ProcessInstance A-2

ProcessInstance A-1

ProcessInstance B-3

ProcessInstance B-2

ProcessInstance B-1

TIBCO Designer

Project

ProcessDefinition A

ProcessDefinition B



Figure 12 A newly created process definition

The process definition describes the business process. When the process definition is executed, it is known as a process instance.

Process definitions consist of these components:

• Activities

• Transitions

• Groups

• Shared Configuration Resources

• Subprocesses

The following sections describe these components. See Developing Process Definitions on page 40 for a description of how to develop your process definitions.

Activities

Activities are the individual units of work within a process definition. Activities are generally operations that interface to external systems, but activities can also perform internal processing. Activities are available on the various palettes within TIBCO Designer. Each palette has a set of activities that can be performed for that palette.

For example, the Adapter palette has activities that can publish messages to a specified adapter or invoke an operation by way of an adapter. There is also an FTP palette that can invoke the PUT and GET commands on an FTP server.


Transitions | 37

Activities are available to communicate with a variety of systems. There is also a general-purpose Java code activity that allows you to write and execute standard Java code to perform custom processing within your process definition.

A process definition can begin with a Start activity, but some palettes contain activities that can start a process. These activities, also known as process starters, begin a process when the specified event occurs. For example, the Mail palette has a Receive Mail activity. If this is placed within a process definition, it replaces the Start activity and a process instance is started when a mail message is received.

Chapter 4, Activities, on page 43 describes activities and their use within process diagrams.

Transitions

Transitions describe the flow of processing within a process definition. A transition is represented by an arrow between two activities. The arrows are unidirectional, and you cannot draw a transition to a previously executed activity. Control flow in a process definition must proceed sequentially beginning with the Start activity (or a process starter) and ending with the End activity.

A transition can optionally specify a condition. The condition determines if the transition is taken when an activity completes processing. After an activity completes, all transitions whose conditions are met are taken. You can have transitions from one activity to many other activities. Therefore, you can have several branches of activity processing in your diagram.

Each activity in a process definition must have a transition to it, or the activity is not executed when the process executes.

Chapter 5, Transitions and Conditions, on page 61 describes transitions and conditions.

Having multiple branches within a process definition does not imply that each branch is processed concurrently. Transitions describe control flow of the process definition, not the concurrency of execution of activities. Process execution is controlled by the process engine. See TIBCO BusinessWorks Administrator’s Guide for more information about configuring the TIBCO BusinessWorks process engine.



Groups

Groups are used to specify related sets of activities. The main uses of groups are the following:

• To create a set of activities that have a common error transition. Basically, this is similar to a try...catch block in Java. This allows you to have a set of activities with only one error-handling transition, instead of trying to individually catch errors on each activity.

• To create sets of activities that are to be repeated. You can repeat the activities once for each item in a list, until a condition is true, or if an error occurs.

• To create sets of activities that participate in a transaction. Activities within the group that can take part in a transaction are processed together, or rolled back, depending upon whether the transaction commits or rolls back.

Chapter 6, Grouping Activities, on page 67 describes groups and how to use them within a process definition.

Shared Configuration Resources

Shared configuration resources are specifications that are shared among activities. These are resources, such as database connections, WSDL files, schema definitions, and connections to other servers. Shared configuration resources are created outside of process definitions, but they are used when specifying the Configuration tab of some activities.

TIBCO BusinessWorks Palette Reference describes shared configuration resources.


Subprocesses | 39

Subprocesses

Business processes are often very complex and it is difficult to diagram the complete process in one process definition. You can create several smaller process definitions instead of one monolithic process definition. You can then call each process definition from another process definition, when necessary. When you call a process definition, the called process is known as a subprocess. Using subprocesses helps to make more readable process diagrams and you can reuse subprocesses across many process definitions.

To create and call a subprocess, follow this procedure:

1. Create a process definition for the subprocess. See Developing Process Definitions on page 40 for more information about creating process definitions.

2. Specify the input and output of the subprocess on the Start and End activities within the subprocess. See Start Activity on page 58 and End Activity on page 59 for more information about specifying the input/output of a process.

3. Create a process definition that will call the subprocess.

4. Place a Call Process activity (located on the General palette) within the process definition.

The Call Process activity allows you to map input values into the called process, and optionally allows you to spawn the subprocess into another process instance.

Normally, a subprocess executes within the same process instance as the calling process, and the output of the subprocess is available to all subsequent activities in the process. If you select the checkbox in the Spawn field of the configuration tab of the Call Process activity, the subprocess is spawned into a new process instance. When a subprocess spawns a new process instance, the parent process cannot access the called process’ output.

Figure 13 illustrates a main process calling a subprocess.

Subprocesses cannot have process starters. That is, they must begin with the Start activity, not any activity that receives an event from an outside source.



Figure 13 A main process calling a subprocess

Developing Process Definitions

Figure 14 describes the general procedure for developing process definitions.

Main Process

Subprocess

Pass customer ID to CreditCheck subprocess. The subprocess returns whether the customer has sufficient credit.

The End activity defines the outcome of the credit check as the output for the process.

Customer ID is defined as input on Start activity.


Developing Process Definitions | 41

Figure 14 Developing process definitions

The following is a more detailed description of how to develop process definitions:

1. Create one or more process definitions by dragging Process Definition resources from the process palette to the design panel. Name each process definition and give the process a description.

2. Create any Shared Configuration resources you will require for your process definition. These items are located in the Shared Configuration palette.

For example, if you are going to connect to a database, you should drag and drop a JDBC Connection into the design panel. This describes the username, password, JDBC URL and other information about the connection. You can then use this connection in many process tasks that require a connection to a database.

See TIBCO BusinessWorks Palette Reference for more details about each of the shared resources.

3. Select one of the process definitions you created in Step 1 in the project panel. This causes a blank business process to appear in the design panel. The business process has a Start and an End activity by default.

See Chapter 4, Activities, on page 43 for more information about activities.

4. Select the activities that start the business process. These activities are known as event sources or process starters. Drag these event sources from their palettes into the design panel.

For example, if you wish to start a process when an HTTP request is received, select the HTTP activity palette, locate the HTTP Receiver process starter activity, and drag and drop it into the design panel.

5. Configure the process starter activities. See the documentation for the activity you are configuring for more information about the fields on each of the tabs for the activity.

Create ProcessDefinition

Create SharedConfigurationResources

Add ProcessStarter

Add Activities

Create TransitionsBetween Activities

Specify EachActivity’s Input

Test/Debug/Redesign



6. Drag and drop more activities to define the business process.

7. Click the transition button on the tool bar to draw transitions between activities.

See Chapter 5, Transitions and Conditions, on page 61 for more information about specifying transitions.

8. Perform mapping and transformation of data for each activity’s input.

See Chapter 7, Mapping and Transforming Data, on page 81 for more information about mapping and transforming data.

9. Once the process definition is complete, use the test mode tool to enter testing mode.

In testing mode, a TIBCO BusinessWorks engine is started to perform the processing described in the process definition. Test and debug your process definition until it operates as expected.

See Chapter 11, Testing Process Definitions, on page 129 for more information about testing process definitions.


| 43

Chapter 4 Activities

Activities perform the work within a process definition. This chapter describes activities and how to use them in a process definition.

Topics

• Activity Overview, page 44

• Activity Icons, page 45

• Configuration, page 47

• Advanced, page 48

• Event, page 49

• Input, page 54

• Output, page 55

• Process Starters, page 56

• Start Activity, page 58

• End Activity, page 59


44 | Chapter 4 Activities

Activity Overview

Activities are the individual units of work within a process definition. Activities are generally operations that interface to external systems, but activities can also perform internal processing. Activities are available on the various palettes within TIBCO Designer. Each palette has a set of activities that can be performed for that palette. For example, the following activities are included in the ActiveEnterprise Adapter palette:

The following are examples of palettes and some of the activities the palettes contain:

• File

— Create File

— Remove File

— Write File

— Read File

• FTP

— FTP Put

— FTP Get

• JDBC

— JDBC Query

— JDBC Call Procedure

— JDBC Update

• Mail

— Send Mail

Table 2 Example activities

Activity Name Function

Publish to Adapter Sends a message to the specified adapter.

Adapter Subscriber Receives a message from the specified adapter and starts a process.

Respond to Adapter Request Replies to a message sent by an adapter.


Activity Icons | 45

When you are within a process definition in TIBCO Designer, the activity palettes are available to drag and drop activities into the process definition. Each activity usually has two or more of the following tabs for specifying the characteristics of the activity:

• Configuration — Used for general configuration of the activity. For example, this tab specifies the adapter service to use for an Adapter activity.

• Advanced — Any advanced configuration parameters are specified here.

• Event — For activities that wait for incoming events, such as HTTP requests or incoming TIBCO Rendezvous messages, this tab specifies the timeout for the incoming event and a condition to determine whether the incoming event is the correct one for the specific process instance.

• Schema — A data schema for the activity. This is used when the input or output data is not known by the activity, and the user must specify their own schema. Once specified, the schema becomes available on the Input, Output or both tabs of the activity.

• Input — The output data from all activities that precede this activity in the process definition is available for mapping to this activity’s input schema.

• Output — The activity’s data is output to activities that follow in the process definition.

The sections that follow describe each tab used to specify an activity. There is a chapter for each available activity palette. See the activity palette chapter for more information about the specific activity you wish to use.

There are two activities that are included in a process definition by default: the Start activity and the End activity. See Start Activity on page 58 and End Activity on page 59 for more information about these activities.

Activity Icons

Each activity is represented by an icon in the palette and design panels. These icons represent the function of the activity. There are some common elements of activity icons that represent the type of activity and the direction of data between the activity and the process.

Table 3 describes the various elements within activity icons.



Table 3 Activity icon elements

Element Example Description

Arrows indicate the direction of information between the process and the external system. Multiple arrows indicate either sending or receiving data, as opposed to performing an operation (see the description of single arrows below).

In the example, the information is flowing from the process to the adapter (the adapter is represented by the purple and blue sphere).

A green circle with an arrow inside (similar to a "Play" button on a media player) indicates the activity is a process starter. These activities start new processes based on the receipt of an event from the external system. See Process Starters on page 56 for more information about process starters.

A yellow square with two parallel lines inside (similar to a "Pause" button on a media player) indicates the activity waits for an incoming event from the external system.

These activities, also known as "Event activities" cause the process to suspend until the incoming event is received. See Event on page 49 for more information about Event activities.


Configuration | 47

Configuration

The configuration tab contains the general specifications for the activity. For example, an FTP activity would contain specifications for the FTP session, such as whether the type of data being sent is text or binary or whether the FTP server resides outside of a firewall. Required fields on the configuration tab are displayed in bold so that it is easy to see the minimum required information for configuration of an activity.

A single arrow going into or out of the external system indicates that the activity is performing a request, sending a response, or performing a request and receiving a response.

This is different from simply receiving a message or data (indicated by multiple arrows) because the activity is performing or responding to a remote operation call.

The direction of the arrow indicates whether the activity is receiving a request, sending a response, or sending a request and receiving a response.

In the Invoke an Adapter Request-Response activity example, the activity is sending a request to an adapter and expects to get a response from the adapter.

In the Adapter Request-Response Server activity example, the activity starts a process based on the receipt of a request from an adapter.

In the Respond to Adapter Request activity example, the activity is sending a response to a previously received adapter request.

Table 3 Activity icon elements

Element Example Description



The following illustrates the configuration tab.

In general, all activities allow you to specify a name for the activity and provide a short description on the Configuration tab. Any other items on the configuration tab are the required configuration elements you must specify to make the activity work.

See the chapter for the palette you are interested in TIBCO BusinessWorks Palette Reference for more information about the Configuration tab of the activities within that palette.

Advanced

The Advanced tab is available on some activities for specifying additional configuration options. See the chapter for the palette you are interested in TIBCO BusinessWorks Palette Reference for more information about the Advanced tab of the activities within that palette.


Event | 49

Event

The Event tab is available on activities that expect an incoming event. These are activities that wait for an incoming event within a process. These activities cause the process instance to suspend until the incoming event is received. An Event tab has the following fields:

The following illustrates the Event tab.

Table 4 describes the available activities with Event tabs. See the chapter for the palette you are interested in for more information about tasks that have Event tabs.

Field Description

Event Key Expression used to evaluate whether the incoming message is appropriate for this process. This expression is specified in XPath, and only data from the incoming event is available for use in this XPath expression. See Chapter 8, XPath, on page 105 for more information about XPath expressions.

Event Timeout The amount of time a message will wait (in milliseconds) if it is received before this task is reached within the process. If the event timeout expires, an error is logged and the event is discarded.



Schema

The Schema tab is used to specify a data schema for input or output of an activity. This is useful when the data does not have a well-known structure. The Schema tab is usually named for the type of schema you are creating. For example, the tab may be named "Input Schema" or "Output Schema".

For example, an email message has a well-known data structure, and therefore does not need a special datatype for its input. A JMS message, however, can have application-specific properties of any datatype. The Schema tab allows you to define the schema for any activities that require a specialized input or output schema.

You can use a simple datatype, or you can define a group of data elements on this tab. You can also reference XML schema or ActiveEnterprise classes stored in the project. Once defined, the schema appears on the Input tab, the Output tab, or both tabs of the activity. The data within the schema then becomes available to other activities within the process definition.

Table 4 Activities with Event tabs

Palette Event Activities Waits For ...

ActiveEnterprise Adapter

Wait for Adapter Message

Wait for Adapter Request

An adapter message or request.

File Wait for File Change The specified file to change.

HTTP Wait for HTTP Request An HTTP request.

JMS Wait for JMS Queue Message

Wait for JMS Topic Message

Either a JMS queue or topic message.

Rendezvous Wait for Rendezvous Message

A TIBCO Rendezvous message.


Schema | 51

The following illustrates the Schema tab. In this example, the Schema tab is labeled "Output Schema" indicating this is the activity’s output.

To define a schema on this tab, use the buttons above the schema tree to add, delete, or move data items. Then use the fields of the dialog to specify the datatype of each item.

Field Description

Name The name of the data item.

Cardinality The qualification for the data item. Data items can be specified as one of the following:

• Required — the data item is required and must be supplied when the process is called.

• Optional — the data item is optional.

• Repeating, Zero or More — The data item is a list that has zero or more elements.

• Repeating, One or More — The data item is a list that has one or more items.

Type The type of data. Can be any of the following:

• XML Element Reference — must locate the stored XML schema definition.

• XML Type Reference — must locate the stored XML schema definition.

• AE Class Reference — must locate the stored ActiveEnterprise class definition.

• Any of the datatypes described in Table 5.



Table 5 describes the datatypes available for data.

Schema Name Stored XML schema that contains the element or type you wish to reference.

Element Name Element within a stored XML schema you wish to reference.

Type Name Type within a stored XML schema you wish to reference.

AE Class Name Stored ActiveEnterprise class you wish to reference.

Table 5 Datatypes for schema items

Icon Description

Complex element. Container for other datatypes. This is a branch in the schema tree.

String or character value.

Integer value. You can specify the size of the integer as one of the following:

• Byte

• Short

• Int

• Long

• Unsigned Byte

• Unsigned Int

• Unsigned Long

• Integer

• Positive Integer

• Negative Integer

• Non-positive Integer

• Non-negative Integer

Field Description


Schema | 53

Floating point number. You can specify the size of the schema item as float, double, or unlimited.

Boolean value.

Date or Time. This can be any of the following datatypes:

• Time

• Date

• Date & Time

• Duration

• Day

• Month

• Year

• Year & Month

• Month & Day

Base 64 or hexidecimal value.

Any Type. Represents a schema item with the TIBCO ActiveEnterprise datatype any. This node can be specified as any other datatype or a reference to an XML Type or AE Class.

Any Element. Represents a schema item that can be a reference to any XML Element. You can use the Set Substitution button to supply a reference to the XML Element for this item.

Choice. Specifies that the schema element can be one of a specified set of datatypes.

Table 5 Datatypes for schema items

Icon Description



Input

The Input tab allows you to map and transform output data from the previous activities in the process (including the event that starts the process) to input data for the activity. The Process Data area contains the output from all of the activities that appear prior to the activity in the process definition. The Activity Input area lists the current activity’s required and optional input data.

The following illustrates the input tab.

Process VariablesThe Process Data area contains all process variables available to the activity. Process variables are data that come from the process, the project, or from other activities in the process. An activity has access to any data that is output from other activities that execute before the activity in the process definition. Process variables are named after the activity whose output they contain. Each process variable begins with a dollar sign ($) to indicate it is a process variable.

There are two process variables that are available to all activities that accept input: $_globalVariables and $_processContext. These variables allow you to access global variables stored in the project as well as information about the currently running process. describes these two process variables.


Output | 55

There is also an $_error process variable available to any activity that occurs after an Error transition in a process definition. See Chapter 9, Error Handling, on page 113 for more information about handling errors.

Mapping and Transforming Activity Input DataYou can create mappings between the available output from previous activities and the current activity’s input. You can also specify constants (strings enclosed in quotes or numbers) for any input values, or you can specify conditions on the mappings.

In general, to create a mapping, you click on the desired item in the available schema in the Process Data panel and drag the item to the desired item in the Activity Input panel. If you wish to type in a constant or expression, you can click on the schema item in the Activity Input panel and type the constant or expression into the field.

There are also several icons above the Activity Input area. Table 8 on page 83 describes the icons and their function.

See Chapter 7, Mapping and Transforming Data, on page 81 for more information about using the Input tab to create mappings between process data and the activity’s input.

Output

The output tab displays the activity’s output schema. This name appears in subsequent activities’ input tabs. The activity’s output data is displayed for informational purposes only and cannot be modified or altered.



The following illustrates the output tab.

Process Starters

Some activities within a palette are used to start a process when an event occurs. For example, in the File palette, there is an activity named File Poller. This activity detects changes in a specified file and starts a process when the change occurs. This kind of activity is known as a process starter. When a process starter is placed into a process definition, it replaces the default Start activity, and becomes the first activity in the process.

You can only have one process starter within a process definition. You will receive a warning if you attempt to add more than one process starter to a process definition. Table 6 describes the available process starters.


Process Starters | 57

When you deploy your project, you can place processes with different process starters on different machines. For example, you may wish to place all processes with a Receive Mail process starter on the same machine as the mail server so that the processes can poll the mail server more efficiently. See TIBCO BusinessWorks Administrator’s Guide for more information about deployment and specifying on which machine process starters are run.

Table 6 Process starters

Palette Process Starter Starts a process when...

ActiveEnterprise Adapter

Adapter Subscriber

Adapter Request-Response Server

A message or a request from an adapter is received.

File File Poller The specified file is created, changed, or deleted.

General Activities

Timer The specified time interval occurs. You can start processes for one-time events or schedule processes to start on recurring time intervals.

HTTP HTTP Receiver An HTTP request is received.

JMS JMS Queue Receiver

JMS Topic Subscriber

Either a JMS queue or topic message is received.

Mail Receive Mail Mail for the specified user is received by the mail server.

Rendezvous Rendezvous Subscriber A TIBCO Rendezvous message is received.

SOAP SOAP Event Source A SOAP web services request is received.

BusinessConnect Receive Request/Notification

A request from a TIBCO BusinessConnect server is received.



Start Activity

The Start activity is the first activity in a process definition (process starters replace the Start activity when they are used in a process definition).

A process can be called from another process, and the Start activity is used to define the input expected by the process. The Start activity has the following tabs:

• Configuration

• Output Schema

• Output

See Subprocesses on page 39 for more information about calling a process from another process.

Configuration The configuration tab has the following fields.

Output SchemaThe Output Schema tab defines the data that the process is expecting as input. Any process that calls this process definition must supply the data specified on the Output Schema tab.

You can define your own datatype on this tab, and you can reference XML schema or ActiveEnterprise classes stored in the project. Once defined, the data specified on the Output Schema tab becomes the output schema of the Start activity. This data then becomes available to other activities within the process definition.

See Schema on page 50 for a description of how to define a schema.

Field Description

Name The name to appear as the label for the activity in the process definition.

Description Short description of the activity.


End Activity | 59

Output The output for the activity is defined by the specified data elements on the Output Schema tab.

End Activity

The End activity is the last activity in a process definition. When a process definition is called from another process, you may wish to have the called process process definition output data to the calling process. You can map data from the activities within the process to an output

schema specified on the End process. This becomes the output of the process.

The End activity has the following tabs:

• Configuration

• Output Schema

• Input

• Error Schema

See Subprocesses on page 39 for more information about calling a process from another process.

Configuration The configuration tab has the following fields.

Output SchemaThe Output Schema tab defines the data that the process will output. Any process that calls this process definition will receive this data when the process call completes.

Field Description

Name The name to appear as the label for the activity in the process definition.

Description Short description of the activity.



You can define your own datatype on this tab, and you can reference XML schema or ActiveEnterprise classes stored in the project. Once defined, the data specified on the Output Schema tab becomes the input schema of the End activity. You can then map data from other activities within the process to the End activity’s input, and this becomes the output of the process when the process completes.

See Schema on page 50 for a description of how to define a schema.

Input The input for the activity is defined by the specified data elements on the Output Schema tab.

Error Schema The Error Schema tab defines schemas to contain data for errors thrown by the process definition. You can define multiple schemas, each for use in specific error cases.

You can define your own datatype on this tab, and you can reference XML schema or ActiveEnterprise classes stored in the project. See Schema on page 50for a description of how to define a schema.

See Chapter 9, Error Handling, on page 113 for more information on error handling.


| 61

Chapter 5 Transitions and Conditions

Transitions and conditions control the flow of activities in a process diagram. This chapter explains how to create transitions and specify conditions on those transitions.

Topics

• Transitions, page 62

• Conditions, page 64


62 | Chapter 5 Transitions and Conditions

Transitions

Transitions describe the flow of processing. A transition is represented by an arrow between two activities or groups of activities in a process definition. The arrows are unidirectional, and you cannot draw a transition to a previously executed activity. Control flow in a process definition must proceed sequentially beginning with the starting activity and ending with the End activity. If you wish to perform looping, use groups to specify multiple executions of grouped activities (see Chapter 6, Grouping Activities, on page 67 for more information on groups).

After an activity or group completes processing, all transitions whose conditions are met are taken. You can have transitions from one activity to many other activities. Therefore, you can have several branches of activity processing in your diagram.

Each activity in a process definition must have a transition to it, or the activity is not executed when the process executes.

Figure 15 illustrates examples of valid transitions in a process. Figure 16 illustrates an invalid transition.

Having multiple branches within a process definition does not imply that each branch is processed concurrently. Transitions describe control flow of the process definition, not the concurrency of execution of activities. Process execution is controlled by the process engine. See TIBCO BusinessWorks Administrator’s Guide for more information about configuring the TIBCO BusinessWorks process engine.


Transitions | 63

Figure 15 Valid transitions

Figure 16 An invalid transition

A transition is taken depending upon the condition specified on the transition. When a transition is created, you may specify whether the transition is taken always, only when an error is encountered, only if no other transitions are taken, or when a custom-specified condition based on process data values is true. See Conditions on page 64 for more information about conditions.

Creating a TransitionTo create a transition, follow this procedure:

1. First create or open a process definition that contains at least two activities.

2. Click on the Create Transition icon on the TIBCO Designer toolbar.

3. Position the cursor over the first activity.

4. Click and hold the mouse button.

One path from Start to End

Two transitions from the Start activity form multiple paths

You cannot transition to a previously executed activity



5. Drag the mouse until the cursor is positioned over the activity that you would like to transition to.

6. Release the mouse button.

Once the transition is created, the condition dialog is presented. The condition dialog allows you to specify when this transition is taken. See Conditions on page 64 for more information about specifying conditions.

Conditions

Conditions are specified on transitions to determine whether to take the transition to the next activity or not. When a transition is created, you are presented with the condition dialog. Figure 17 illustrates the condition dialog.

Figure 17 The condition dialog

You must specify the type of condition, the following table describes each type.

Condition Type Description

Success Take this transition unconditionally. That is, always transition to the activity the transition points to, if the activity completes successfully.

This is the default condition for transitions.


Conditions | 65

When a transition is created, the default condition type is "Success". If a condition other than "Success" is specified, it is displayed on the transition line in the process definition.

Success with condition

Specify a custom condition using XPath. If the activity completes successfully, and the condition you create evaluates to true, the transition is taken to the activity it points to.

You can type in an XPath condition, and you can use the XPath formula builder to drag and drop XPath expressions and data into the condition. See Chapter 8, XPath, on page 105 for more information about specifying XPath conditions and using the XPath formula builder.

Success if no matching condition

Take this transition when the activity completes successfully, but only if no other transitions are taken. This is useful when multiple transitions with conditions are drawn to other activities. This condition type can be used to handle any cases not handled by the conditions on the other transitions.

Error Take this transition if there is an error during processing of the activity.

See Chapter 9, Error Handling, on page 113 for more information on error handling in process definitions.

Condition Type Description

There can be only one "Error" and one "Success if no matching condition" transition out of each activity.




| 67

Chapter 6 Grouping Activities

This chapter describes groups and how to use them for transactions, error-handling, and looping.

Topics

• Overview of Groups, page 68

• No Action Groups, page 72

• Overview of Loops, page 73

• Iterate Loop, page 75

• Repeat Until True Loop, page 76

• Repeat On Error Until True Loop, page 78


68 | Chapter 6 Grouping Activities

Overview of Groups

Groups are used to specify related sets of activities. The main uses of groups are the following:

• To create a set of activities that have a common error transition. Basically, this is similar to a try...catch block in Java. This allows you to have a set of activities with only one error-handling transition, instead of trying to individually catch errors on each activity. See No Action Groups on page 72 for more information.

• To create sets of activities that participate in a transaction. Activities within the group that can take part in a transaction are processed together, or rolled back, depending upon whether the transaction commits or rolls back. See Transaction Groups on page 73 for more information about transactions.

• To create sets of activities that are to be repeated. You can repeat the activities once for each item in a list, until a condition is true, or if an error occurs. See Overview of Loops on page 73 for more information about loops.

Groups have a Configuration tab and an Output tab. The output of all activities within a group is available to any subsequent activities in the process definition. If the group is to be repeated, only output of the last execution of each activity in the group is available. For Iterate and Repeat Until True loops, you can optionally accumulate the output of each execution of one activity in the group into a list. This list becomes the group’s output and the list is available to subsequent activities in the process definition. For other types of groups, no output is available.

To group a set of activities, perform the following procedure:

1. Choose the Select tool (the arrow pointer in the tool bar).

2. In the design panel, draw a box around the desired activities.

3. Choose View>Group from the menu, or click the Create a group icon.

4. The group configuration appears in the configuration panel.

5. Specify the type of group to create and any other configuration parameters required for the group. See Table 7 for more information about the fields of the group configuration tab.

To ungroup a set of grouped activities, perform the following procedure:

1. Choose the Select tool (the arrow pointer in the tool bar).

2. Select the group in the design panel.


Overview of Groups | 69

3. Choose View>UnGroup from the menu, or click the Undo the group icon.

Table 7 Group configuration tab

Field Description

Name The name to appear as the label for the group in the process definition.

Description Short description of the group.

Group Action The type of group. Groups can be of the following types.

• None — Used for grouping without looping. See No Action Groups on page 72 for more information.

• Transaction Groups — Used to group activities that participate in a transaction. Only JDBC activities within a transaction group are committed or rolled back when the transaction completes. See Transaction Groups on page 73 for more information.

• Iterate Loop — Used to iterate a group once for every item in a list. See Iterate Loop on page 75 for more information.

• Repeat Until True Loop — Used to iterate a group until the specified condition is true. See Repeat Until True Loop on page 76 for more information

• Repeat On Error Until True Loop — Used to iterate a group when an error occurs. See Repeat On Error Until True Loop on page 78 for more information.

Group Action: Iterate

Index Name The index variable for the loop. This variable will be used to store the current iteration number of the loop. The index starts at one and increments by one with each execution of the loop.

See Index Variable on page 74 for more information.

Variable List The list you wish to use as the source of the iterations. The group will iterate once for each item in the list.



Accumulate Output Specifies that you wish to accumulate the output of one of the activities in the group into a process variable.

By default, only the output of each activity from the last execution of a loop is available to subsequent activities in the process definition. With this option checked, each execution of the loop stores the selected activity’s output into the next position of a process variable. See Accumulate Output on page 74 for more information.

Output Activity The activity within a group for which you wish to accumulate output for each execution of the loop. You may select only one activity within the group.

Output Name The name of the process variable to store the successive output of the selected activity in the Output Activity field.

Group Action: Repeat-Until-True



Conditions The condition that specifies when the loop should stop. The activities within the group are executed once, then the condition is checked. If the condition evaluates to false, the loop repeats, if the condition evaluates to true, the loop stops. The loop continues to repeat until the condition evaluates to true.

The condition is specified as an XPath condition and the XPath formula builder is available to help to create the condition. See Chapter 8, XPath, on page 105 for more information.


Field Description


Overview of Groups | 71

Accumulate Output Specifies that you wish to accumulate the output of one of the activities in the group into a process variable.

By default, only the output of each activity from the last execution of a loop is available to subsequent activities in the process definition. With this option checked, each execution of the loop stores the selected activity’s output into the next position of a process variable. See Accumulate Output on page 74 for more information.

Output Activity The activity within a group for which you wish to accumulate output for each execution of the loop. You may select only one activity within the group.

Output Name The process variable to store the successive output of the selected activity in the Output Activity field.

Group Action: Repeat-On-Error-Until-True



Conditions The condition that specifies when the loop should stop. The activities within the group are executed once. If an error occurs during the processing of the activities, and that error does not have an associated error transition, the condition is checked.

If the condition evaluates to false, the loop repeats, if the condition evaluates to true, the loop stops. The loop continues to repeat if unhandled errors are encountered, until the specified condition evaluates to true.

The condition is specified as an XPath condition and the XPath formula builder is available to help to create the condition. See Chapter 8, XPath, on page 105 for more information.


Field Description



No Action Groups

You can group a set of related activities, with a common set of transitions into and out of the group. If you do not wish for the activities within the group to repeat, specify the group action to be None. No action groups are primarily useful for specifying a single error transition out of the group so that if an unhandled error occurs within the group, you only need one error transition instead of an error transition for each activity. This behavior is similar to a try...catch block in Java.

The following process definition illustrates a no action group that has one error transition out of the group to process any unhandled errors that occur when the group’s activities execute.

The process performs the following operations:

1. An FTP Get activity retrieves a file from an FTP server.

2. A Write File activity writes the retrieved file so that its contents are available at a later time.

3. The contents of the file are used to create an HTTP request to a web server.

Suspend (If Still Error)

Suspends the process if the error still occurs when the specified condition is true. See Suspend If Still Error Option on page 79 for more information about this field.


Field Description


Transaction Groups | 73

4. In the event of an error, a TIBCO Rendezvous message is published so that an administrative application can be notified of the error. If all activities within the group succeed, an email message is sent.

Transaction Groups

A transaction group either commits or rolls back activities within the group when the transaction completes. Only JDBC activities participate in the transaction, but other activities can be part of the transaction group. If the transaction commits, all JDBC activities within the transaction group commit, if the transaction rolls back, all JDBC activities within the transaction group roll back.

The transaction group commits automatically if all activities within the group complete and a non-error transition is taken out of the transaction group. If any errors occur while processing the activities within the group, the transaction is rolled back and the error is returned (you should have an error transition out of the group to handle this situation).

Individual JDBC activities can override the default transaction behavior and commit separately. See the description of the JDBC palette in TIBCO BusinessWorks Palette Reference for more information about specifying JDBC activities.

Overview of Loops

Loops allow you to execute a series of activities more than once. You can iterate based on the items in an array stored in the process data, you can iterate until a given condition is true, or you can iterate if an error is encountered while processing. The following are the types of loops that are available:

• Iterate Loop

• Repeat Until True Loop

• Repeat On Error Until True Loop



When a loop completes executing, the output of the last execution of each activity within the loop is available to any subsequent activity in the process definition. If you map the output of an activity within a loop to the input of an activity later in the process definition, the data that is mapped when the process is run is the data that is output for that activity during the last execution of the loop.

Iterate and repeat until true loops allow you to accumulate the output of a single activity within the loop for each execution of the loop. This allows you to retrieve output from each execution of the activity within the loop. See Accumulate Output on page 74 for more information about accumulating the output of each iteration of a loop.

Index VariableThe index variable is used to hold the current number of times a loop has executed. The iteration count starts at one the first time the loop is executed, and the count increases by one for each iteration of the loop.

You can access this variable like any other process data by referencing it with a dollar sign ($) in front of it. For example, if the index variable is i, and you want to specify a condition that the loop should execute three times (for a repeat until true loop), the condition would be $i=3.

Accumulate OutputFor iteration and repeat until true loops, you can accumulate the output of one of the activities within a group by checking the Accumulate Output field. If you check this field, you can select one of the activities in the group, and each time the loop is executed, the selected activity’s output is placed into a list. The list of accumulated output for that activity is stored in a variable whose name is specified in the Output Name field. This variable can be accessed in the same way other process data can be accessed by other activities after the loop exits.

Because you can accumulate output from only one activity in a group, you should design your group in such a way that there is only one activity within the group that holds the data you wish to accumulate for each iteration. For example, you may want to accumulate a list of customer names from repeated executions of a JDBC Database Query task, or you may wish to accumulate the sum of the amounts for line items within an order.

If there are several activities that you want to accumulate output from, you should create a Java Code activity to concatenate the data into the output parameters for the Java Code activity. You can then choose the Java Code activity as the Output Activity to accumulate for each iteration of the loop.


Iterate Loop | 75

The output for the selected activity is accumulated each time the activity is executed. Therefore, if you choose to accumulate the output of the same activity used in the condition of a Repeat Until True loop, the activity is executed and the output is added to the list before the condition is checked. In this case, you may wish to use a Mapper activity within the loop to accumulate the output. The Mapper activity would be placed after the activity used for the condition of the loop so that the loop exits before the value is accumulated. Alternatively, you can place a Mapper activity outside of the loop to strip out the unwanted value from the output list after the loop exits.

Iterate Loop

An Iterate loop repeats the series of grouped activities once for every item in an existing sequence or list. The list can be items of any datatype. The following is an example of an iterate loop.


1. A JDBC Query activity is used to query a database and populate a list of customer records. The customer records are then passed to a group containing one activity, WriteCustomerList.

2. The WriteCustomerList activity writes the name and address of each customer to a file, appending to the file as each record is written.

3. The group iterates once for every customer record returned by the QueryCustomer activity, and transitions to the ReadCustomerList activity once the last record is processed.

4. The process then reads the file that was written so that its data is available to the process, then transitions to a Send Mail activity to send the contents of the customer list by way of email.



The following is the configuration for the WriteAllCustomers group:

In this example, accumulating the output of the WriteCustomerList activity would not be appropriate because that activity is appending each customer record to a file.

Repeat Until True Loop

The Repeat Until True loop repeats the series of grouped activities until the given condition evaluates as "true". The activities are always executed once before checking if the condition is true. After executing the series of activities, the condition is checked, and the loop exits when the condition evaluates as "true". The following is an example of a Repeat Until True loop.



Repeat Until True Loop | 77

1. A group of activities executes until the customer records have all been queried. The group consists of:

b. A Java Code activity that outputs all the valid customer IDs. When all valid IDs have been output, the activity will output -1 to indicate no more records can be queried.

c. A JDBC Query activity that takes each ID and queries a database for the record matching the ID.

d. A Send Mail activity that uses the customer information retrieved from the database to send an email to the customer notifying the customer of new product offerings.

For each iteration of the loop, the output of the QueryCustomer activity is placed into a variable named customerList.

5. Once the condition of the loop evaluates to true, the loop stops executing and transitions to the WriteCustomerList activity so that the customer list will be stored in a file.

The condition looks at the value of CustomerID/ID_num. The Customer ID activity outputs -1 when there are no more customers, so the condition examines the value and when it is -1, the loop can exit.

The following is the configuration for this example Repeat Until True loop.



Repeat On Error Until True Loop

The Repeat On Error Until True loop allows you to repeat a series of activities in the event that an unhandled error occurs. The activities are executed once, if there are no unhandled errors, the loop is terminated. If an error occurs for which there is no error transition, the condition of the loop is evaluated — if the condition is true, the loop is exited, if the condition is false, the loop is repeated until there is no error or the condition is true.

For example, you may wish to execute a series of activities and retry the execution in the event of an unhandled error. However, you may wish to only retry the execution three times, so that you can avoid an infinite loop if the error occurs repeatedly. In this case, you would specify a repeat on error until true loop with a condition that specifies the execution should stop after three tries.

The following illustrates a repeat on error until true loop.


1. An FTP Get activity retrieves a file from an FTP server.

2. The contents of the file are written so the data is available at a later time.

3. The contents of the file are sent by way of email.


Repeat On Error Until True Loop | 79

The following is the configuration for this example loop:

The condition is specified as $i = 5, which means that when the index variable is equal to five (that is, the fifth iteration of the loop), the loop exits. The condition is only evaluated upon encountering an unhandled error within the group. If an error is encountered, then the loop will exit if the condition evaluates to true. The resulting behavior in this example is that the group of activities will execute and loop until a successful completion of all activities or the group is executed five times.

Suspend If Still Error OptionRepeat On Error Until True loops have the "Suspend If Still Error" option. When this option is checked, the process instance suspends if the error still exists when the condition of the loop is true. The suspended process is displayed by TIBCO Administrator, and the deployment configuration allows you to specify an action to perform if the process is suspended.

This option allows the administrator to correct the problem causing the error (for example, a machine may be down, or an adapter service may not have been started on the machine). Once the problem is corrected, the administrator can resume the process execution.

When a process instance resumes execution, the execution resumes before the Repeat On Error Until True loop. The process instance will try to execute the loop, and all process variables are reset to their values before the loop was executed the first time. Therefore, the process instance resumes execution as though the Repeat On Error Until True loop had never executed. The loop is entered again, and if an error occurs, the loop condition is checked as it normally would be.



If the error persists, the process instance will continue to suspend. The administrator can decide whether to resume or kill the process if the error cannot be fixed.

For more information about deployment configuration and specifying actions to perform if processes are suspended, as well as information about how to view suspended processes and resume or kill them, see TIBCO BusinessWorks Administrator’s Guide.


| 81

Chapter 7 Mapping and Transforming Data

This chapter describes mapping data from a process to a specific activity’s input. and how to transform the data using the activity’s input tab.

Topics

• Overview of Mapping and Transformation, page 82

• Mapping Data, page 88

• Effects of Mapping, page 90

• Transforming Data, page 97

• Modify Statement, page 97

• Set Substitution, page 102


82 | Chapter 7 Mapping and Transforming Data

Overview of Mapping and Transformation

On the Input tab of an activity, you can see the available process data and the activity’s input. The process data and activity input are represented as schema trees. The process data is the list of available data within the process definition at the point where the activity is located (an activity has access to all output data from any activity that is executed before it in the process definition). The activity input is the list of input values that are required or optional for the activity.

You can specify a formula for each item in the activity. XPath is the language used for the formula, but you do not need detailed knowledge of XPath to create simple formulas. For the most part, you can drag and drop items from the process data schema to the activity input schema, and the correct XPath expression appears automatically. This chapter describes how to create basic expressions; for more advanced use of XPath, see Chapter 8, XPath, on page 105.

For more information about mapping and transformation, see the following topics:

• Specifying Constants on page 87

• Mapping Data on page 88

• Effects of Mapping on page 90

• Transforming Data on page 97

• Modify Statement on page 97

• Set Substitution on page 102

When you specify the input schema for an activity, the specification is represented internally as Extensible Stylesheet Language Transformation (XSLT) code. Normally, you do not need to examine the XSLT code generated by the mappings. However, if you are familiar with XSLT and you wish to see the actual code, you can right-click on any item in the input schema and choose Copy from the popup menu. Then open a blank text document and choose Paste. The XSLT is displayed in your text document.

You can also use your own XSLT documents to perform transformations instead of using the techniques described in this chapter. The XSLT File shared configuration resource and the Transform XML activity allow you to use your own XSLT code. See TIBCO BusinessWorks Palette Reference for more information and examples of using XSLT to perform mapping.


Overview of Mapping and Transformation | 83

Icons on the Input TabThe Process Data area has two buttons and the Activity Input area has four buttons. Table 8 describes the buttons available in the Activity Input area.

Table 8 Input tab buttons

Icon Description

Process Data Area

Enables/disables the "show data" mode. In show data mode, an additional area appears on the input tab that displays the actual data values of the activity’s input based on the specified mapping and expressions.

Show data mode is most useful when testing for displaying the current contents of an activity’s data. However, you can use this mode while designing your process definition to enter actual data values in the process data area. The data will be transformed using the specified mappings, and the result is displayed in the Activity Input Data area.

Allows you to specify a type for Process Data items that are specified as the any datatype.

The any datatype can be assigned to a schema element which can hold a value that is of "any" type, basic or otherwise, and is made available in the repository. When a schema that contains an any datatype appears in the Process Data schema, you replace the any datatype with the actual schema.

See Set Substitution on page 102 for more information about this button.

Activity Input Area

Shows/hides the explanation panel at the bottom of the Input tab.

The explanation panel provides a Formula field where you can enter an XPath formula for the input item. The Status field displays any errors or warnings for the current mapping, or the status of the entire Input tab, if no items are selected.



Shows/hides the mapping formulas next to the input item.

Allows you to insert or modify a statement. You can create the following statments:

• if — conditionally map output

• choose — conditionally map output

• list — handle multiple input items

• copy-of — copy nodes with the same name and structure

• copy-contents-of — copy nodes with different names but the same structure

You can also modify or delete a statement you have already inserted.

See Modify Statement on page 97 for more information about this button.

Adds a process variable for use within the current mapping. When you click this button, a dialog appears asking you to name the variable you would like to add.

When you add a named variable, it appears in the Activity Input and Process Data areas. You can supply any XPath expression to the new variable in the Activity Input area (either through mapping or through the XPath Formula Builder), and the datatype of the new variable changes to the datatype of the result of the XPath expression.

Once the variable’s contents have been supplied, the variable (in the Process Data area) can be mapped to any activity input item.

Adding a variable is useful when you wish to join two repeating elements into a single list, then map the combined list to an activity input item. Adding a variable is also useful if you perform the same computation repeatedly. You can map the results of the computation to several activity input items instead of recreating the computation for each item.


Icon Description


Overview of Mapping and Transformation | 85

Schema elements also have a set of associated icons to indicate their type. Table 9 describes the icons used for schema items.

Allows you to specify a type for input items that are specified as the any datatype, choice datatypes (unions), or subclasses (complex elements with an "Any Type" subclass).

The any datatype can be assigned to a schema element which can hold a value that is of any type, basic or otherwise, and is made available in the repository. This icon becomes available for schema items whose datatype can be substituted for an actual datatype. When you use this icon to replace the datatype, the datatype of the item becomes the datatype you specify.

See Set Substitution on page 102 for more information about this button.

Invokes the XPath formula builder. You can use this editor to create an XPath statement for this input item. See Chapter 8, XPath, on page 105 for more information about XPath and the XPath formula builder.

Table 9 Icons for schema items

Icon Description

Sequence of elements. Container for other datatypes. This is also called a branch in the schema tree.

Simple string or character value.

Simple integer value.

Simple decimal (floating point) number.

Simple boolean value.


Icon Description



Schema elements are either in black or red text. Black text signifies that the mapping for the item is acceptable. Red text signifies the mapping contains an error. Errors can be caused by many things: required items are not mapped, the XPath formula contains an error, and so on. Place the cursor in the schema element that is red and consult the status message while the status information is displayed for more information about the errors for schema elements that are red.

Schema elements can have an additional qualification of being required, optional, or repeating. Table 10 describes the additional qualifiers that appear next to the name of schema items.

Simple Date or Time. This can be any of the following datatypes:

• Time

• Date

• Date & Time

• Duration

• Day

• Month

• Year

• Month & Year

• Day & Month

Simple binary (base 64) or hex binary value.

Represents a schema item that can be any datatype. Data in this schema element can be any datatype.

Choice. Specifies that the actual schema element can be one of a specified set of datatypes.

Table 10 Additional icons for items

Qualifier Description

? A question mark indicates an optional Item.

* An asterisk indicates the item repeats zero or more times.

Table 9 Icons for schema items

Icon Description


Specifying Constants | 87

Specifying Constants

For each item in the activity input schema tree, you can specify a constant. Constants can be strings or numeric values. To specify a string, enclose the string in quotes. To specify a number, type the number into the schema item’s mapping field. The following illustrates specifying the string "USA" for the Country item and 94304 for the PostalCode item of an input schema.

Constants can also be used within functions and search predicates. To learn more about complex XPath expressions that use functions and search predicates, see Chapter 8, XPath, on page 105.

Date and Datetime Strings in ConstantsIn constant expressions used in activity input bindings, datetime values are read in according to the ISO 8601 standard, as described in the XML Schema specification. For example, the value:

"2002-02-10T14:55:31.112-08:00"

is 55 minutes, 31 seconds and 112 milliseconds after 2pm on February 10th, 2002 in a timezone that is 8 hours, 0 minutes behind UTC.

+ A plus sign indicates the item repeats one or more times.

Table 10 Additional icons for items

Qualifier Description



If no timezone field is present, the value is interpreted in the timezone of the machine that is performing the parsing. This can lead to complications if you are processing data from different timezones, so you are encouraged to always use timezones.

When TIBCO BusinessWorks generates datetime strings (for example in the process debugger display for process data), it always uses UTC time. The above value would therefore be output as:

2002-02-10T14:55:31.112Z

which is the equivalent time in the UTC timezone.

Mapping Data

You map data by selecting an item within the Process Data area, then dragging and dropping that item into the desired schema element you wish to map in the Activity Input area. When you perform mapping, an arrow appears as you drag the data element to the Activity Input area. When you release the mouse, the XPath expression for the desired data element from the Process Data area appears in the expression field for the schema element you are mapping.

Figure 18 illustrates dragging and dropping a schema item from the Process Data area to the Activity Input area.

Figure 18 Mapping activity input

Notice that the XPath expression starts with a dollar sign, indicating the root nodes within the Process Data tree.


Mapping Data | 89

In the example above, NodeP in the Activity Input area is mapped to $Start/Branch3/NodeD. The path starts at one of the root elements in the Process Data ($Start), and uses slashes to indicate sub-elements. See Chapter 8, XPath, on page 105 for more information about XPath and locating elements within a schema tree.

Evaluation ContextEach item in the Process Data area has a path to describe its location within the process data tree. Each activity has a root node in the process data tree. Each item below a root node is referenced by placing forward slashes between the items within the path. For example, consider the following structure within the process data tree and the activity input.

Branch1 in the process data tree is referenced as $Branch1. NodeA of Branch1 would be referenced as $Branch1/NodeA.

The evaluation context sets the path for a branch in the Activity Input area. All sub-items within the branch then reference items within the process data tree relative to the branch’s evaluation context.

Process Data

Branch1-

Branch2+

Branch3-

NodeA

NodeB

NodeC

NodeD

Branch4-

Branch5+

Branch6-

NodeX

NodeY

NodeZ

NodeP

Activity Input



Mapping Branch1 of the process data to Branch4 of the activity input sets the evaluation context of Branch4 to $Branch1. Thus, if you choose to map $Branch1/NodeC to NodeX of Branch4, the mapping will appear as "NodeC" in the activity input area instead of "$Branch1/NodeC" because the evaluation context for Branch4 is Branch1. The following illustrates the mapping:

If you wish to map Branch4/NodeX to Branch3/NodeD, the mapping appears as "../Branch3/NodeD" because the evaluation context is set to Branch1. The relative path to Branch3/NodeD is up one level and then the rest of the path. The following illustrates mapping Branch4/NodeX to Branch3/NodeD when Branch4’s evaluation context is set to Branch1.

Effects of Mapping

Elements in the process data and activity input trees can be either simple data or branches.

• Simple elements are data items of a particular type (for example, string, integer, or boolean).

• Branches are structures that contain other data items (branches can contain either simple elements or other branches).

Both simple data and branches can be repeated. Repeating items contain multiple elements, similar to an array or list. You can create a mapping between various types of items.


Effects of Mapping | 91

Table 11 describes the effect of mapping simple elements and branches from the process variables to the activity input.

Table 12 describes the effect of mapping repeating to non-repeating items from process variables to activity input.

Table 11 Mapping simple elements and branches

Activity Input →

Simple Element Branch

Process Variable ↓

Simple Element

Maps the simple data from the process variable to the simple data of the activity’s input.

Not a useful mapping.

Branch Not a useful mapping. Sets the evaluation context of the branch to the process variable branch.

Table 12 Mapping repeating and non-repeating items

Activity Input →

Non-Repeating Repeating

Process Variable ↓

Non-Repeating Table 11 describes mapping non-repeating simple elements and branches.

Sets the evaluation context of the repeating item in the activity input to the non-repeating item in the process variable and creates one element for the input repeating item.



The following sections are a series of examples of each of the possible useful mappings.

Simple Element to Simple Element Mapping a simple element to another simple element results in the runtime data of the process variable being supplied as the activity’s input for that schema item. In the example below, the GetOrderId/ID variable is supplied to the OrderId schema item.

Branch to BranchMapping a branch to a branch sets the evaluation context of the branch to the process variable branch.

In the example below, the input schema item ShipName is mapped to the process variable GetCustomerInformation. This sets the evaluation context of ShipName to $GetCustomerInformation. Sub-items of ShipName can then reference sub-items of GetCustomerInformation without specifying the complete path. Therefore the mapping between ShipName/CustomerName and GetCustomerInformation/Name is displayed as "Name" in the expression field of the input schema item.

Repeating Maps the value of the repeating item in the process variable to the non-repeating item in the activity input.

Only one element is required in the activity input item, so you must specify a filter to determine which element within the repeating item should be mapped to the non-repeating item.

Sets the evaluation context of the repeating item in the activity input to the repeating item in the process variable.

Also, creates one element in the input repeating item for every element of the repeating process variable.

Table 12 Mapping repeating and non-repeating items



Any items in the Activity Input that have the same name as the items in the process variable are automatically mapped. In the example above, Street, City, and State have the same name, so they are automatically mapped when GetCustomerInformation is mapped to ShipName.

In the special case where the branch schema input item is identical to the process variable branch item, the mapping automatically creates a copy of the process variable for the schema input items.

You are asked when creating this mapping if you wish to create a copy of the input items. If any mappings exist for the sub-items, they are deleted. A dialog appears asking you to confirm your action in either case:

Dialog when creating a copy Dialog when creating a copy and sub-items are already mapped



When a copy is created, the Activity Input schema item changes to indicate the kind of copy. If the branches have the same name, the item becomes a "copy-of", if the branches have different names, the item becomes a "copy-contents-of". The following illustrates both cases:

Non-Repeating to RepeatingMapping a non-repeating item to a repeating item creates one input item. A repeating item in the activity’s input creates one item for every item in the process variable it is mapped to. Because the repeating input item is mapped to a single, non-repeating item, one item is created.

In the example below, the OrderItem repeating schema input item is mapped to the process variable branch GetOrderInformation/OrderDetails. This sets the evaluation context of items in the repeating input item to $GetOrderInformation/OrderDetails. The sub-items of OrderItem can refer to any items with the process variable OrderDetails without referencing the full path. One input element is created because the repeating item is mapped to a non-repeating branch.

Copy-Of

Copy-Contents-Of



Repeating to Non-Repeating Mapping a repeating item to a non-repeating item requires that you use a search predicate to filter the repeating item and select which element of the repeating item to map to the non-repeating item.

In the example below, the OrderDetails input schema item is mapped to the repeating process variable GetOrderInformation/OrderDetails/OrderItem. The branch must be mapped to a single value, so a filter expression must be used to determine which element of the process variable should be mapped to the simple element. In this example, the filter is [1], which means to select the first element. You can create a more complex filter, for example [ProductId="3A54"] which selects the element whose attribute ProductId is equal to "3A54". See Search Predicates on page 108 for more information about using search predicates.

Repeating to RepeatingMapping a repeating item to a repeating item creates one input element for every element of the repeating process variable.



In the example below, the OrderDetails/OrderItem repeating schema input item is mapped to the GetOrderInformation/OrderDetails/OrderItem repeating process variable. Because the evaluation context is set to the process variable, sub-items of the schema input do not need to reference the full path of the process variable sub-items. For each element in $GetOrderInformation/OrderDetails/OrderItem, one element is created in the activity input item.

In the special case where the repeating schema input item is identical to the process variable repeating item, the mapping creates a copy of the process variable for the schema input items. See Branch to Branch on page 92 for more information about creating copies of input items.

Mappings That Are Not UsefulMappings are generally not useful if the mapping results in no input data. The Input tab permits you to make the mapping, but a warning is given in the information panel. The two mappings which are generally not useful are branch to simple element and simple element to branch.

If you map a branch to a simple element, the branch itself has no data (its sub-items contain the data), so the value of the input simple element would not have a value at runtime. If you map a simple element to a branch, that sets the evaluation context for the branch to the simple value. Because the simple element has no sub-items, the only purpose to this mapping is if you wish to map all of the branch’s sub-items to the same simple element. In that case, the path to that simple element would be "." indicating it is the same element as the evaluation context.

The following illustrates mapping a simple element to a branch and mapping the branch’s sub-items to the same simple element. You could achieve the same goal by mapping the branch’s sub-items individually.


Transforming Data | 97

Transforming Data

If you wish to change the data before it gets placed into the activity input schema, you can use any valid XPath expression in the schema item’s expression field. You can type in the XPath expression into the activity input item’s expression field, or you can click the XPath formula builder button to create an XPath expression.

The XPath formula builder is a GUI tool for creating and manipulating XPath expressions. See Chapter 8, XPath, on page 105 for more information about creating XPath expressions and the XPath formula builder.

Modify Statement

The Modify Statement button allows you place a statement into the desired element of the input schema. You can put any of the following statements into a schema item for conditional mapping:

• If — allows you to map a schema item based on a condition.

• Choose — allows you to map a schema item based on one or more conditions, and you can optionally specify an "otherwise" condition.

• List — allows you to handle items of a repeating schema element separately.

• Copy-Of — allows you to copy nodes with the same name and structure.

• Copy-Contents-Of — allows you to copy nodes with different names but the same structure.



To use the Modify Statement button, perform the following:

1. Click on the schema item’s mapping field.

2. Click the Modify Statement button.

The Modify Statement dialog appears to allow you to specify the statement you wish to insert into the input schema. You can also use this dialog to change or delete an existing statement you have already specified.

The following sections describe the various types of statements in more detail.

If StatementsIf statements allow you to map data based on a condition. This is useful if you wish to map an optional item based on whether the condition is true. If the condition is false, the schema item remains unmapped.

For example, you might want to specify that if the customer has a state specified in their address, then map the country for shipping to the constant "USA". If there is no state specified, then do not map the country because the customer either has an invalid address, or they are in a different country.

To create an If statement, perform the following procedure:

1. Place the cursor in the activity input schema item you wish to conditionalize.

2. Click the Modify Statement button. You will be presented with the Modify Statement dialog.

3. Select "If" as the type of statement.

The following illustrates an Modify Statement dialog specifying an If statement.

4. Click the OK button.

The input mapping tab changes to have a condition instead of the original item in the schema.


Modify Statement | 99

5. Create a mapping to the condition as you normally would create mappings. That is, drag and drop schema elements from the Process Data panel to the Activity Input panel.

In the example below, the Country field is set differently depending upon whether the State item is not empty. If the State is not empty, the Country is set to the constant "USA". If the State is empty, then the Country is not mapped.

You can specify any valid XPath expression for the "If" condition or for the mapping or transformation of the input schema items.

Choose StatementsYou can create a Choose statement by selecting the "Choose" option of the Modify Statement dialog. The Choose statement provides a set of conditions and the mapping to use when the condition is true.

To create a Choose statement, perform the following procedure:

1. Place the cursor in the activity input schema item you wish to conditionalize.

2. Click the Modify Statement button. You will be presented with the Modify Statement dialog.

3. Select "Choose" as the type of statement.

4. Enter the number of conditions you wish to specify, and check the "Include Otherwise" option if you wish to have a mapping when no conditions evaluate to true.

The following illustrates an Modify Statement dialog specifying one condition and an otherwise condition.



5. Click the OK button.

The input mapping tab changes to have a series of conditions instead of the original item in the schema.

6. Create mappings to the conditions as you normally would create mappings. That is, drag and drop schema elements from the Process Data panel to the Activity Input panel.

In the example below, the RequiredDate field is set differently depending upon the priority of the customer. If the customer is important, the RequiredDate is set to the date entered on the order. If the customer is not marked as "VIP", then the required date is set to the date on the order plus fifteen days.

You can specify any valid XPath expression for the "When" conditions or for the mapping or transformation of the input schema items.

List StatementsThe List option of the Modify Statement dialog allows you to create a fixed number of list items that you can treat individually. The List option provides a series of mappings instead of one mapping for the whole list. An example of using a list statement would be to create one mapping for the first element of the


Modify Statement | 101

list, and have a different mapping for the rest of the list. This would be useful if you want to have a standard first element (for example, to qualify for a discount, you must order the featured sale item for the month), and a variable list for the rest of the elements.

To create a list mapping, perform the following:

1. Place the cursor in the activity input schema item you wish to manipulate.

2. Click the Modify Statement button.

3. Choose "List" as the type of statement. List mappings are only available for repeating schema items.

4. Type the number of items you wish to map in the Entry Count field.

The following illustrates an Modify Statement dialog specifying two entries in a list.

Once you specify the number of items in the list, the input mapping tab changes to have a series of list items instead of the original item in the schema.

5. Create mappings to the list items as you normally would create mappings. That is, drag and drop schema elements from the Process Data panel to the Activity Input panel.

In the example below, the first list item is mapped to a fixed product ID, quantity, and price. The remaining list items are mapped to the process data.



Copy-Of and Copy-Contents-OfCopy-Of and Copy-Contents-Of statements are created automatically when you create a mapping between branches with the same structure. Copy-Of statements are created when the branches have the same name. Copy-Contents-Of statements are created when the branches have different names.

You can create Copy-Of or Copy-Contents-Of statements manually using the Modify Statement dialog for an item, but normally this is not useful. You can remove Copy-Of or Copy-Contents-Of statements if you no longer need them by choosing the item with the statement, then using the "Delete Statement" option on the Modify Statement dialog.

Set Substitution

The Set Substitution button allows you to specify the datatype of schema items that do not have a specific datatype. This includes items of the following types:

• ActiveEnterprise type any

• Choice (unions)

• Any Element

• items whose subclass is type Any Type

Using set substitution causes the schema element to become the datatype specified. When you specify the actual datatype for the schema element, mappings can be made using the items available in the actual schema that will substitute for the any datatype at run time.


Set Substitution | 103

To use set substitution, place the cursor in the Process Variable or Activity Input schema item that is of type any that you wish to specify. Then click on the Set Substitution button. You will be presented with the following set substitution dialog.

You can choose to substitute an XML Type or an AE Class for the schema element. You can browse the elements available using the Browse button, and you can click the Go To button to display the definition of the selected schema element. Once you have chosen the substitution type, click OK. The schema element changes from the any datatype to the datatype you specified in the substitution. You can then map the substituted schema element as you would map any other schema element.




| 105

Chapter 8 XPath

XPath (XML Path Language) is an expression language developed by the World Wide Web Consortium (W3C) for addressing parts of XML documents. XPath also has basic manipulation functions for strings, numbers, and booleans.

TIBCO BusinessWorks uses XPath as the language for defining conditions and transformations. For a complete description of XPath, refer to the XPath specification (which can be obtained from www.w3.org). This section attempts to cover the basics of XPath and its use in TIBCO BusinessWorks.

Topics

• XPath Basics, page 106

• The XPath Formula Builder, page 108


106 | Chapter 8 XPath

XPath Basics

TIBCO BusinessWorks uses XPath (XML Path Language) to specify and process elements of data schema. These data schema are either process variables or input schema for an activity. You can also use XPath to perform basic manipulation and comparison of strings, numbers, and booleans. To use XPath in TIBCO BusinessWorks, you need only be familiar with the basic XPath concepts, but you may wish to learn more about XPath when building complex expressions. For a complete description of XPath, refer to the XPath specification (which can be obtained from www.w3.org).

Addressing Schema ElementsAll process variables and activity input are represented as an XML schema. Regardless of where the data comes from or its format, TIBCO BusinessWorks represents the data as a schema tree. The data can be simple (strings, numbers, booleans, and so on), or it can be a complex. Complex elements are structures that contain other schema elements, either simple elements or other complex elements. Both simple and complex elements can also repeat. That is, they can be lists that store more than one element of the given type.

XPath is used to specify which schema element you would like to refer to. For example, the following schema may be available for an activity’s input:


XPath Basics | 107

The process data area of the example input tab illustrates the output schema of the activities in the process. There are three output schema, each a root node in the process data area: GetCustomerInformation, GetOrderInformation, and GetOrderId. Each of these schema has its own associated structure, for example, GetCustomerInformation has a set of simple values and GetOrderInformation has simple data and other complex data.

To reference a particular data item in any of these schema, you start with the root node and then use slashes (/) to indicate a path to the desired data element. For example, if you wish to specify the Street attribute within the ShipName complex element that is in the GetOrderInformation node, you would use the following syntax:

$GetOrderInformation/ShipName/Street

The path starts with a dollar sign to indicate it begins with a root node, then continues with node names using slashes, like a file or directory structure, until the desired location is named.

Evaluation ContextXPath also has a method for referencing relative paths from a particular node. If you have an evaluation context, or a particular starting node in a schema tree, you can specify the relative path to other elements in the tree.

For example, if your evaluation context is $GetOrderInformation/ShipName, then you can reference the sub-items of ShipName without specifying the entire path. If you wish to reference $GetOrderInformation/RequiredDate, the relative path would be ../RequiredDate. The path is relative to the evaluation context — RequiredDate is one level higher in the schema tree than the elements of ShipName.

See Evaluation Context on page 89 for more information about using the evaluation context while mapping.

NamespacesSome schema elements must be prefixed with their namespace. The namespace is automatically added to elements that require this when creating mappings on the Input tab of an activity or when dragging and dropping data in the XPath Formula Builder.



Search PredicatesAn XPath expression can have a search predicate. The search predicate is used to locate a specific element of a repeating schema item. For example, the $GetOrderInformation/OrderDetails/OrderItem item is a repeating element. If you wish to select only the first item within the repeating element, you would specify the following:

$GetOrderInformation/OrderDetails/OrderItem[1]

The [1] specifies the first element of a repeating item.

Sub-items can also be examined and used within a search predicate. For example, to select the element whose ProductId is equal to "3A54", you would specify the following:

$GetOrderInformation/OrderDetails/OrderItem[ProductId="3A54"]

You can also use functions and expressions within the search predicate. For example, if you wish to find all elements after the first, you would specify the following:

$GetOrderInformation/OrderDetails/OrderItem[position()>1]

See the online documentation available within the XPath formula builder for a list of the available operators and functions in XPath.

You can also build custom Java functions and make them available in XPath by using the Java Custom Function shared resource. See the description of the Java Custom Function shared configuration resource in TIBCO BusinessWorks Palette Reference for more information about creating custom functions and making them available in XPath.

The XPath Formula Builder

The XPath formula builder can be used where XPath expressions are allowed, such as when creating transformations on the Input tab of an activity. The XPath formula builder allows you to drag and drop schema elements and XPath functions to create XPath expressions. The schema elements, when dragged into the XPath Formula field, automatically become valid XPath location paths for the desired item. If a function is dragged into the XPath formula window, there are placeholders for each parameter of the function. You can drag and drop schema elements over the parameter placeholders to replace each placeholder.


The XPath Formula Builder | 109

Figure 19 illustrates using the XPath formula builder to drag and drop schema elements into function placeholders.

Figure 19 The XPath formula builder

Table 13 describes the different areas of the XPath formula builder.

Table 13 XPath formula builder elements

Element Description

Data tab Displays the process data schema tree. All elements in this tree are available to drag and drop into the XPath Formula field.



Figure 20 illustrates using the XPath formula builder to create a valid function. The function concatenates the data elements $GetCustomerInformation/Street and $GetCustomerInformation/City and places a space between the two elements.

Functions tab Displays the available XPath functions. These are categorized into groups and each function can be dragged from the function list into the XPath Formula field.

When the function is placed into the XPath formula, placeholders are displayed for the function’s parameters. You can drag and drop schema elements from the Data tab into the function’s placeholders.

The result of evaluating the function is displayed in the "Expression Evaluates To" panel. If there are any errors in the expression, they are listed there as well.

For more information about XPath functions, see the description of the function that is displayed when it is selected in the XPath formula builder.

Documentation panel Describes each selected function. As you click on a function in the Function tab, the documentation panel gives a brief description of the function and one or more examples.

Evaluation Context field Displays the evaluation context of the expression field that the editor was invoked from. See Evaluation Context on page 107 for more information about the evaluation context.

XPath Formula field Displays the XPath formula you wish to create. You can drag and drop items from the Data tab or the Functions tab to create the formula.

Expression Evaluates To Panel

Displays the result of evaluating the formula shown in the XPath Formula field. If there are errors in the formula, they are displayed here.

Table 13 XPath formula builder elements

Element Description


The XPath Formula Builder | 111

Figure 20 Creating an XPath formula




| 113

Chapter 9 Error Handling

When executing business processes, activities can encounter errors. You may wish to add procedures to your process definitions for handling any expected or unexpected errors. This chapter describes error handling in process definitions.

Topics

• Overview of Error Handling, page 114

• The $_error Process Variable, page 114

• Error Propagation, page 115

• Process Error Schemas, page 117


114 | Chapter 9 Error Handling

Overview of Error Handling

Errors can occur during activity processing. For example, an error may occur during a Send Mail activity if the specified mail host does not exist. You can specify that one transition out of an activity is to be taken in the case of an error. You then specify activities you wish to execute in the event of an error. This allows you to create error-handling procedures for dealing with potential runtime errors in your process definitions.

For example, the following illustrates a simple process that begins with an HTTP request and updates a database based on the incoming request. If the update is successful, the process ends. If an error is encountered (for example, the database is down), an email is sent to a system administrator, and then the process ends. Figure 21 illustrates this simple error-handling procedure. The error transition is used to specify what activities should execute in case of an error.

Figure 21 A simple error-handling procedure

Error handling can also involve significantly more complex processing. The following sections describe error handling in more detail.

The $_error Process Variable

When an error transition is taken, the $_error process variable is available to all subsequent activities in the process definition. The schema of the $_error variable is the following:


Error Propagation | 115

The contents of each schema item are dependent upon the activity that throws the error. The Data schema item contains an XML string with activity-specific error information. You can use the Parse XML activity to parse this XML string and view the error data for the activity.

When you create an error-handling procedure, you may find the data in the $_error process variable useful. You can map data from this process variable into Input items for activities in your error-handling procedure.

Error Propagation

Called processes and groups propagate any unhandled errors to the parent process. Unhandled errors occur where there is no error transition that specifies what activities to execute in the case of an error. Also, you can use the Generate Error activity to create an unhandled error. The Generate Error activity does not permit any transitions to another activity, so any error created by the Generate Error activity is propagated to the parent process.

The following sections describe propagation of errors for groups and called processes.

Group Error PropagationUnhandled errors halt the execution of a group and the error transition out of the group is taken. Figure 22 illustrates a process definition that waits for new text files, parses the files into an XML schema, then inserts the records into a database table.

Figure 22 Propagating errors from a group



The process definition uses two group activities. The first group is an iterate group that performs one update for each record. If any of the updates fail, an error transition out of the group is taken to the WriteLogEntry activity. A second group surrounds the iterate group to enclose all updates in a transaction. If the transaction succeeds, the process ends. If the transaction fails, the error transition is taken out of the transaction group to the SendMail activity.

The Generate Error activity is used to propagate an error outside of the transaction group to the parent process. If the iterate group experiences an error, the WriteLogEntry activity is executed, then the error transition from the Null activity is taken to the Send Mail activity.

The Send Mail activity is reached if there is either an error when committing the transaction or if the Generate Error activity is executed (because of an error in the iterate group). The $_error process variable contains the error information for the activity where the error occurred.

The Generate Error activity can use any error schemas defined on the process to propagate a specific schema to the parent process. See Process Error Schemas on page 117 for more information about process error schemas.

Called Process Error PropagationWhen a process definition calls another process definition, the called process can encounter errors. Any unhandled errors encountered when executing the called process cause the called process to halt execution and return the error to the parent process. Figure 23 illustrates a process definition that waits for an incoming HTTP request that contains an order.

Figure 23 Propagating errors from a called process

The GetCreditLimit process is called to check the credit limit of the customer that places the order. If the credit limit check succeeds, the ProcessOrder process is called. If the order processing is successful, a response is sent back to the customer stating the order is complete and the process definition terminates.


Process Error Schemas | 117

If the GetCreditLimit or ProcessOrder processes encounter an error, a response is sent back to the customer stating there was an error in the order and the process definition terminates.

The $_error process variable contains the error information for the activity where the error occurred. Also, a process can define an error schema and use the Generate Error activity to propagate specific data to the parent process. See Process Error Schemas on page 117 for more information about process error schemas.

Process Error Schemas

The $_error process variable contains the default data returned in the event of an error. You can define specific error schemas to hold error data when errors are propagated from a group or a called process. Each process can define a number of error schemas by creating these schemas on the Error Schema tab of the process definition’s End Activity.

Error schemas are created like any other schema (see Schema on page 50). However, the Error Schema tab of the End activity allows you to create more than one error schema. Figure 24 illustrates the Error Schemas tab with two error schemas. The left panel of the tab allows you to create or delete schemas. The middle portion allows you to modify the selected schema. The right panel of the tab allows you to modify each schema item.

Figure 24 The Error Schemas tab



Error schemas are used by the Generate Error activity. When the Generate Error activity is executed, the specified error schema is propagated to the parent process. Figure 25 illustrates the Configuration tab of the Generate Error activity. The Select Error Schema field contains a drop-down list of error schemas defined for the process.

Figure 25 The Generate Error Configuration tab

If - Default - is chosen for the error schema, only the $_error process variable contains the propagated error data.

If a process error schema is chosen, the schema appears in the Input tab for the Generate Error activity and you can map data to the specified error schema. At runtime, the Generate Error propagates the specified error schema to the parent process in the $_error_<activity-name> process variable.

The process variable is named after the activity where the Generate Error occurred. If the Generate Error occurs in a called process, the <activity-name> portion of the process variable is the name of the Call Process activity. If the Generate Error occurred within a group, the <activity-name> portion is the name of the Generate Error activity within the group.

In the example described in Called Process Error Propagation on page 116, the SendErrorInOrder activity will have access to the error schema supplied by any GenerateError activity in the GetCreditLimitProcess. This process specifies two error schemas, InvalidCustomer and NotEnoughCredit. Figure 26 illustrates the process data available to the SendErrorInOrder activity.

Figure 26 Example of process data for error schemas


Process Error Schemas | 119

The available error schemas for the GetCreditLimit process are presented as a schema item of type Choice. This item will contain either the InvalidCustomer or the NotEnoughCredit error schema. You can use XPath to determine which schema is actually contained in the element, and then map the data in the schema accordingly.

See TIBCO BusinessWorks Palette Reference for more information about the Generate Error activity.




| 121

Chapter 10 Inter-Process Communication

Executing process instances can communicate and can pass data between each other. The General Activities palette contains the Wait and Notify activities and the Receive Notification process starter for implementing inter-process communication. This chapter describes inter-process communication and provides examples of its use.

Topics

• Overview of Inter-Process Communication, page 122

• Data for Inter-Process Communication, page 123

• Coordinating Inter-Process Communication, page 124

• Database Storage for Wait/Notify/Receive Notification Information, page 125

• Examples of Inter-Process Communication, page 125


122 | Chapter 10 Inter-Process Communication

Overview of Inter-Process Communication

TIBCO BusinessWorks allows two executing process instances to communicate. You may need process instances to communicate if you wish to synchronize process execution or if your processes must execute in a specific order.

TIBCO BusinessWorks provides the Wait and Notify activities and the Receive Notification process starter to handle inter-process communication. These activities are similar to semaphores in programming. A process containing a Wait activity waits for another process to execute a corresponding Notify activity. Alternatively, the Receive Notification process starter creates a new process instance when another process executes the corresponding Notify activity.

The data sent between the activities is defined by a Notify Configuration shared configuration resource. The Notify activity only sends information to the Receive Notification process starter or Wait activity that specifies the same Notify Configuration resource. The schema supplied to the Notify Configuration resource can be empty, if you do not wish data to be sent between processes. However, the Notify Configuration resources must be the same for the Notify, Receive Notification, or Wait activities if they are to be used to communicate with each other.

A string-based key is used to coordinate between Wait/Notify/Receive Notification activities to determine when a Notify activity corresponds to a Wait or Receive Notification. The key is supplied to the Notify activity, and any Wait activity that matches that key is executed when the Notify occurs.

When a Notify activity executes its information is stored until a matching Receive Notification or Wait activity accepts the information. The Notify activity executes immediately and transitions to the next activity. The Notify activity cannot be used to determine when a corresponding Receive Notification or Wait has received the information.

In general, using inter-process communication consists of these steps:

1. Define the data that must be passed between the processes by creating a Notify Configuration shared configuration resource.

2. Determine the key that correlates processes with Notify activities with the corresponding processes with Receive Notification process starters or Wait activities.

3. Create process definitions that use the Receive Notification, Wait, and Notify activities. These activities are located in the General Activities palette. See TIBCO BusinessWorks Palette Reference for more information about the configuration requirements for each of these activities.


Data for Inter-Process Communication | 123

4. If your process engines are on different machines, ensure that you are using a database to store process instance information. Wait/Notify information is stored in a database so that process engines on different machines can share information.

The following sections describe these steps in more details. See Examples of Inter-Process Communication on page 125 for more specific examples of when inter-process communication may be needed.

Data for Inter-Process Communication

The Notify Configuration shared configuration resource defines the data that the Notify activity passes to the corresponding Wait activity or Receive Notification process starter. The schema for the data is defined in the same way as any other schema is defined. See Schema on page 50 for more information on specifying schemas.

The same Notify Configuration resource is used to configure the Notify activity as well as the Wait activity and the Receive Notification process starter. The schema in the Notify activity’s configuration appears in the Notify activity’s input schema. This allows you to map process variables to the Notify activity’s input. The Notify activity then passes its data to its corresponding Wait or Receive Notification.

The Wait activity and Receive Notification process starter have output that matches the Notify Configuration specified on their Configuration tab. This allows you to use the data passed by the process with the Notify activity in subsequent activities after the Receive Notification or Wait activities.

If you wish only to signal the waiting process to continue but not exchange data, the Notify Configuration schema used by the Notify/Receive Notification/Wait activities can be empty. However, the same Notify Configuration resource must be specified by corresponding Notify and Receive Notification or Wait activities. Only activities with the same Notify Configuration resource can communicate with each other.



Coordinating Inter-Process Communication

When configuring Receive Notification, Wait, and Notify activities, you must specify a key to coordinate which actives correspond to each other. You can also specify a timeout for how long the information about Wait and Notify activities is kept before it is removed from storage. The following sections describe configuring the key and timeouts for inter-process communication.

Specifying the KeyTo configure Receive Notification, Wait, and Notify activities, you must specify a key that corresponds Notify activities with Receive Notification or Wait activities. The key is a string that corresponding activities specify to determine when a Receive Notification or Wait activity should accept data from a Notify activity. The key is similar to event keys used in activities that wait for incoming events (described in Event on page 49). The key is a string, but you can use any XPath expression that evaluates to a string when the process instance executes.

Each Notify activity corresponds to exactly one Receive Notification or Wait activity. That is, as a Notify activity executes, the first Receive Notification or Wait activity that matches the Notify’s key can then execute. You can execute many Notify activities with the same key, but

You can create one-to-one correspondence between Wait and Notify activities so that exactly one process’ Notify activity corresponds to one other process’ Receive Notification or Wait activity. Or, you can create many-to-one relationships so that many Notify activities’ keys can correspond to the Receive Notification or Wait in one process. A Notify, however, always only corresponds to only one Receive Notification or Wait activity. Therefore, once a Notify executes, the corresponding Receive Notification or Wait activity continues processing.

See Examples of Inter-Process Communication on page 125 for examples of specifying keys for Wait/Receive Notification/Notify activities.

Timeouts for Notify and WaitNotify and Wait activities have associated timeouts. Timeouts specify how long information for the Notify and Wait is kept before it is removed from storage.

XPath expressions can be used to specify the key for Wait and Notify activities. The Receive Notification process starter can specify a global variable or a fixed string for its key.


Database Storage for Wait/Notify/Receive Notification Information | 125

The Notify activity executes immediately and transitions to the next activity in the process definition. However, the timeout for the Notify activity specifies how long the information about the Notify should be kept. If no corresponding Wait activity executes before the specified timeout, the Notify information is removed. Once Notify information is removed from storage, it cannot be accepted by the corresponding Wait activity.

The Wait activity causes process execution to pause until a corresponding Notify activity with a matching key executes. The Notify activity could execute before the corresponding Wait activity and its information could be waiting in storage. If the Notify has not executed, the process instance containing the Wait suspends until the Notify occurs or the Wait activity’s specified timeout is reached.

The Receive Notification process starter does not have a timeout because it creates a process instance only when a corresponding Notify activity executes.

Database Storage for Wait/Notify/Receive Notification Information

If your process engines are located on different machines, a database is required to store process instance state for inter-process communication. When process engines reside on different machines, they must share information about pending Wait/Receive Notification/Notify activities.

A database allows process engines to share process instance state information across machines in a domain. Your deployment configuration must specify a database for process engine storage if you expect process instances on different machines to have corresponding Wait/Receive Notification/Notify activities.

See Configuring Storage for Process Engines on page 150 for more information on specifying a database for process engine storage.

Examples of Inter-Process Communication

The following sections describe situations where inter-process communication may be necessary.



Enforcing Order for Process ExecutionIf you wish process instances to execute in a certain order, you can use Wait and Notify activities to accomplish this. This requires that some portion of the incoming event is used to determine the order.

For example, an application may assign a priority number to incoming orders. This may be important when accepting requests for a limited resource (for example, airplane seats or available space in a university class). The orders must be processed in order to ensure that orders with the highest priority number have access to the resource first. Figure 27 illustrates an example process definition that orders incoming events.

Figure 27 Ordering incoming events

In this process definition, new requests are submitted by way of a web interface. A new process is started for each request, and a priority number (an ordered sequence) is given with each request. The order with priority number "1" is submitted, and processed immediately. When the first order is completed, a Notify is sent with its key set to "1". All other orders transition to the Wait activity. These orders are suspended until a Notify is executed whose key is equal to their priority number minus one (that is, the order with the next highest priority number).

Using this technique, orders are processed in the order of their priority, regardless of when the order is submitted. All orders create a process instance and then immediately suspend until the Notify is sent from the order with the next highest priority.

Multiple Types of Incoming Events Resume a Running ProcessSome processes require a "Wait for ..." event (for example, Wait for Adapter Message) to continue processing. This occurs when the process requires an external application to send an additional request.

For example, a new order arrives, and because the total is over $100,000, it requires approval before processing. You may notify a group of approval managers by email, and then any of the approval managers can respond by email or by way of a web interface for approval. Figure 28 illustrates this set of process definitions.


Examples of Inter-Process Communication | 127

Figure 28 Multiple event sources to continue a process

The Wait/Notify activities would use the OrderID as the key to coordinate which order the Notify corresponds to. In this case, it would be possible for more Notify activities to execute than Wait activities. You must configure the Notify activities to have an appropriate timeout so that the Notify information is removed if it is not used by the associated Wait activity.

Scalability With Incoming EventsYou may use a protocol to distribute incoming events across multiple process engines, such as TIBCO Rendezvous Distributed Queues or Java Messaging Service (JMS) queues. This allows for greater scalability because the load of incoming events is distributed. However, if you have a "Wait for ..." activity (for example, Wait for Queue Message) in your process definition, the incoming event will be received by all process instances across the multiple process engines. This can potentially decrease the performance because of greater network traffic, depending upon how many process instances are running.

Orders can be approved by mail or by web. Whitchever Notify occurs first is accepted by the Wait

Incoming Order process handles orders less than $100,000 immediately.Orders greater than $100,000 require appoval by a person.



Ideally, you should create some mechanism so that incoming events are handled outside of the process definition and then routed to only the correct process definition. The Wait and Notify activities can accomplish this. You would replace your "Wait for ..." activity with a Wait activity. Then, you create a new process definition that contains a process starter to handle the incoming event. Your new process would then use the Notify activity to send the data from the incoming event to the correct process instance with the corresponding Wait activity.

Specific Protocol RequirementsSome business processes use protocols with specific requirements that make inter-process communication necessary. For example, you may have a process that starts when a TIBCO Rendezvous Certified Message (RVCM) arrives. Your process may also require a Wait for Rendezvous Message listening on the same subject as the process starter. This specific configuration would be difficult to implement because incoming messages would create new processes and also be sent to the waiting activities within the process.

In the example above, the business requirements necessitate working around the requirements of the RVCM protocol. To accomplish this, you may be able to change your business requirements, or you can use the Wait and Notify activities to create two process definitions.

The first process definition accepts all new messages and determines (based on message content) whether the message should start a new process or be passed to an activity within the process waiting for the message. The process would execute a Notify activity for the new message, but the key of the Notify would be different depending upon whether a new process must start or if the message is to be sent to an executing process. The second process definition would start with a Receive Notification process starter and have a Wait activity in place of the Wait for Rendezvous Message activity. This configuration allows the first process to receive all incoming messages, parse them to determine the appropriate action, and then pass each message to the appropriate process.


| 129

Chapter 11 Testing Process Definitions

This chapter describes the testing mode available for stepping through your process definitions and examining process data.

Topics

• Overview of Testing, page 130

• Breakpoints, page 131

• The Test Window, page 132

• Process Instances During Testing, page 133

• Stepping Through a Process, page 135

• Colors in Test Mode, page 135

• Test Mode Buttons and Menus, page 137


130 | Chapter 11 Testing Process Definitions

Overview of Testing

TIBCO BusinessWorks provides a testing environment for stepping through your process models and determining the sources of errors. Entering the testing environment starts a TIBCO BusinessWorks engine. The engine starts process instances based on the process definitions stored in your project. You can select one of the running process instances to display in the design panel, and the currently executing activity is highlighted as the process instance runs.

In general, testing should be done during the design and development phase of a project. Testing a deployed project is possible, but might be difficult depending upon the volume of the workload of the system. Also, testing involves setting breakpoints within the process model to stop the running process instances at desired points. This could adversely affect the performance of a production environment, so you may want to use a development system for testing purposes.

Testing a process definition typically involves these steps:

1. Select the process definition you wish to test in the project panel.

2. Set breakpoints in the process definition at points where you wish to stop a running process and examine its state. See Breakpoints on page 131 for more information.

3. If the process begins with a Start activity and the Start activity has a schema defined, you can supply input data to the process before executing it.

4. Click the Display Tester Window button to display the test window. From the test window you can start process instances or load more process definitions. See Process Instances During Testing on page 133 for more information about process instances in the test window.

5. Examine the data of the process by selecting any of the activities in the process. The activity’s current data is displayed on the Input and Output tabs.

6. Use the toolbar buttons (Pause Testing, Step to Next Activity, and so on) in the testing window to either continue through the process instance or to stop the current process instance. See Stepping Through a Process on page 135 for more information about stepping through process definitions.


Breakpoints | 131

Breakpoints

Breakpoints allow you to suspend a running process instance at a specified point so that you can examine the process’ data. Breakpoints persist after you close your project—the breakpoints you set should appear in the process definition once the project is reopened.

You can set breakpoints before or after an activity executes. The only exceptions to this are that you cannot set a breakpoint before the starting activity or after the End activity. You can also specify that each breakpoint should only occur based on a given condition. Conditions are specified in XPath, just like conditions for items in an activity’s input.

To set a breakpoint, click the Set Breakpoint button and the Set Breakpoint dialog appears. The dialog allows you to select whether a breakpoint should occur before or after (or both) any of the activities within the current process definition executes. Figure 29 illustrates an example of the Set Breakpoint dialog.

Figure 29 Set breakpoints dialog

You can choose to select all of the activities by clicking the Select All button. You can clear all set breakpoints by clicking the Clear All button.

You can also set or clear breakpoints on individual activities by right-clicking on the activity and choosing Set/Clear BreakPoint Before/After from the popup menu. Using the popup menu on the activity only sets the specified breakpoint, you must use the Set Breakpoint dialog if you wish to specify a condition for the breakpoint.

When a breakpoint is set on an activity, a red hexagon (a stop sign) appears next to the task’s icon to indicate the task has a breakpoint. A breakpoint before the activity appears to the top left of the activity, a breakpoint after the activity appears to the top right of the activity. Figure 30 illustrates a process diagram that has breakpoints set before and after two activities.



Figure 30 Setting a breakpoint

When you are testing process instances, the process definition can be displayed in the design panel. When a process instance is stopped at a breakpoint, the breakpoint icon becomes a stop sign inside of a yellow triangle to indicate where the process instance has stopped. Figure 31 illustrates the example process definition when the process instance is stopped at the breakpoint before the ReadFile activity.

Figure 31 Process instance stopped at a breakpoint

The Test Window

You can begin testing a process definition by selecting it in the project tree panel, then clicking the Display Test Window button on the toolbar. The test window displays process instances created during testing. Figure 32 illustrates the test window.

Figure 32 The test window


Process Instances During Testing | 133

You can select process instances in the test window and display the process definition. See Process Instances During Testing on page 133 for more information about process instances in the test window.

The test window has several buttons on its toolbar for manipulating process instances. See Test Mode Buttons and Menus on page 137 for a complete description of the buttons in the test window.

Process Instances During Testing

Entering test mode creates a process engine that loads the currently displayed process definition and all of its dependent subprocesses. If you wish to load other process instances into the process engine, you can use the Load Processes button

in the test window. When you start testing, you can create process instances for all loaded process definitions.

If the loaded process begins with a Start activity that requires input, you can supply input to the process starter by clicking on the Supply Input Data button

. This button is not available for processes that do not require input data on the Start activity.

Creating Process InstancesIf the loaded process begins with a Start activity, one process instance is created to execute the process definition. Processing continues until the End activity is reached.

If the loaded process begins with a process starter (for example, Adapter Subscriber), the process engine waits for an incoming event before creating a process instance. Each incoming event causes a process instance to be created, and each process instance is listed in the test window. You can select any process instance in the test window and view it in the design panel.

You can create new process instances of any loaded process using the Create a Job button in the tester window. Select a process definition in the tester window, then click the Create a Job icon. A new process instance for that process definition is created.



Working With Process InstancesEach process instance is independent in the test window. You can start/stop/step through each process instance individually.

When a process instance is running, its description is (running) in the test window. Once a process instance completes its processing (that is, its End activity is reached), its description is changed to (completed job) in the test window. You can view any running or completed job. When a job is selected in the test window, its process definition is displayed in the design panel and its description changes from (running) or (completed job) to (viewed job). Figure 33 illustrates process instances and their labels in the test window.

Figure 33 Multiple process instances in the test window

You can stop the execution of a process instance by selecting it and clicking the Stop the Current Job button in the tester window.

You can delete any completed process instances from the test window by selecting the process instances and clicking the Delete a Completed Job button .

You can browse or change any process definition or any activity’s configuration while in test mode, but changes will not take effect during the current testing session. You must exit test mode and re-enter test mode for changes to take effect.


Stepping Through a Process | 135

Stepping Through a Process

When you set a breakpoint in a process definition, the process executes all activities up to the activity with the breakpoint. Once the breakpoint halts processing, you can step through the process using the toolbar icons or menu items. Stepping through the process allows you to examine the executing process instance at your own pace. You can step to the next activity, step into or out of a subprocess, or you can choose another activity later in the process definition and execute from the current point to that later activity. See Test Mode Buttons and Menus on page 137 for more information about the toolbar icons and menu items that allow you to step through a process.

When stepping through a process definition, activities are executed as you pass them. The currently highlighted activity is executed after you choose your next step. If there are multiple paths within a process definition, all transitions that evaluate to true are taken, but only one path is chosen to be highlighted as the next activity when you choose Step to Next Activity.

When you choose to step through a process, breakpoints are still honored, no matter which menu item or toolbar icon you choose. For example, if you are currently within a subprocess and you choose the Step Out of a Subprocess menu item or toolbar icon, execution continues until the next breakpoint occurs or processing of the subprocess completes. If there is a breakpoint before the subprocess completes, processing halts at that breakpoint, and you must choose Step Out of Subprocess again to continue processing.

Colors in Test Mode

When you run a process definition in test mode, the elements of the process change colors depending upon what is occurring in the executing process instance. Table 14 describes the colors of each element in a process definition and its significance.

Table 14 Colors in test mode

Color/Element Description

Black transition arrow The transition has not yet been evaluated.



Green transition arrow The transition has been evaluated, and its condition evaluates to true. Therefor the transition is taken to the next activity.

Red transition arrow The transition has been evaluated, and its condition evaluates to false. Therefore the transition is not taken.

Red activity The activity encountered an error while processing. Any Call Process activity that calls a process in which an error occurs is also red.

Bright yellow activity The process definition is paused at this activity. This could be either because the activity has a breakpoint set or because the Step to Next Activity or Run To This Resource menu item was used.

The activity has not yet executed, but it is the next activity to execute when the process instance continues.

Yellow activity The activity is currently executing, but the focus is not on the activity. This can occur if you have multiple paths in your process definition and the focus is not on the current path.

Table 14 Colors in test mode

Color/Element Description


Test Mode Buttons and Menus | 137

Test Mode Buttons and Menus

There are three buttons on the TIBCO Designer toolbar used when testing process definitions. There is also a View->Test menu that performs the same actions as the toolbar buttons. Table 15 describes these buttons and menu items.

The test window also has several buttons for manipulating the process instances during testing. The View->Test menu has menu items that perform the equivalent actions as these buttons. Table 16 describes these buttons and menu items.

Table 15 Toolbar icons for testing

Button/ Icon

View->Test Menu Item Description

Show Debug Window

Displays the test window. The currently selected process definition and all its dependent subprocesses are loaded.

Set Breakpoints Brings up the Set Breakpoint dialog that allows you to specify which activities should have breakpoints. Breakpoints stop the process instance and allow you to examine process data before the process continues.

Add Input Data Allows you to specify data for the process starter’s input schema. This icon is enabled only for process definitions that begin with a Start activity that requires an input schema.

This brings up a dialog for creating an input schema. You can use this dialog to save the input data you supply to disk.

Table 16 Test window icons

Button/ Icon


Start Once testing is started process instances are created.

Once in testing mode, your process definition cannot be changed. Return to design mode by using the Stop Testing icon if you want to add/remove/change process definitions.



Resume Resumes any process instances that are paused or stopped at a breakpoint.

Load Process and Start

Allows you to specify processes to load.

Only the selected process and dependent subprocesses are loaded when the test window is first displayed. This icon/menu item allows you to load other process definitions for testing.

Pause Testing Temporarily suspends the process instance. Resume the process instance with the Resume icon.

Step Over When a process instance is paused on an activity, click this icon to step ahead in the process definition and execute the next activity.

Step Into Once a Call Process activity is reached, this icon allows you to display the process definition of the called process and step through it.

This icon is only available when Call Process is the next activity to be processed.

Step Out After stepping into a subprocess, this toolbar icon can be used to return to the process that called the subprocess.

This icon is only available when you are within a subprocess.

Show Current Job Location

When a process instance is paused at a breakpoint or any other point, you can change focus to display or edit other resources in your project. This icon and menu item allow you to return focus to the process definition for the currently running process instance.

Focus returns to the highlighted activity within a process where the process instance is paused.


Button/ Icon



Test Mode Buttons and Menus | 139

There are also menu items on the popup menus for each activity within a process definition. You can access these menu items by right clicking on the activity. These are the popup menu items for activities that are used in testing: Set Breakpoint Before, Set Breakpoint After, Clear Breakpoint Before, Clear Breakpoint After, and Run To This Resource.

Stop Testing Kills the current engine and exits testing mode (all process instances are removed from the testing window). You must click the Start or Load Process icon to start another engine if you wish to resume testing.

Go To Started Process

This item is available only on the View>Test menu, there is no toolbar icon.

Displays the process definition with which you began this testing session.

Deletes the selected jobs marked as (completed job) from the test window. You can only delete completed jobs.

Creates a new process instance for the selected process definition.

Stop Current Job


Stops the currently executing process instance, but does not exit test mode. This is useful if you wish to examine the data of the process instance, but you do not want to continue running the process.

Moving Ball Options


Brings up a dialog that allows you to set whether the moving ball is displayed. The moving ball shows the current execution path.

You can also set the speed of the moving ball.


Button/ Icon




The Set/Clear Breakpoint Before/After menu items sets or clears the specified breakpoint on the selected activity.

The Run To This Resource menu item executes the running process instance up to the selected activity. For example, if a process instance is halted on a breakpoint, selecting an activity later in the process definition and choosing the Run To This Resource menu item resumes processing of the process instance and executes all activities between the breakpoint and the selected activity. The process instance pauses when it reaches the activity where you selected the Run To This Resource menu item.


| 141

Chapter 12 Implementing a Deployment Configuration

This chapter describes the process for creating a deployment configuration and sending that configuration to the TIBCO Runtime Agent (TRA).

Topics

• Overview of Deployment, page 142

• Creating a Deployment Configuration, page 143

• Sending a Deployment Configuration to the TRA, page 145

• Starting Deployment Components, page 147

• Undeploying, page 147

• Controlling Execution of Process Instances, page 148

• Configuring Storage for Process Engines, page 150

• Configuring Fault-Tolerant Engines, page 152


142 | Chapter 12 Implementing a Deployment Configuration

Overview of Deployment

A deployment configuration is the description of the physical layout of components (adapter instances and process engines) within a TIBCO administration domain. The deployment configuration can also specify conditions to monitor on each machine. You specify the deployment configuration by using the TIBCO Designer Deployment palette, and save the deployment configuration as part of the project. Each project has only one deployment configuration, but you can have multiple projects within an administration domain.

Before creating a deployment configuration, the project must be saved as a server-based project in the administration server repository. If you are developing the project locally (that is, the project is stored in a local file), you must save the project as a server-based project. See Saving Projects on page 18 for more information about saving server-based projects.

Once the deployment configuration has been created, you can click the Deploy button in TIBCO Designer. The appropriate information (for example, which adapters or process engines are to run on this machine) is sent to the TIBCO Runtime Agent (TRA) on each machine. The TRA on each machine manages the components on that machine and communicates with the administration server about the state of the running components. This allows you to start, stop, and monitor components from the TIBCO Administrator GUI.

Figure 34 illustrates a deployment configuration.

Figure 34 Sample deployment configuration

Domain

MyProject

ProcessEngine 3

TIBCO Adapter forPeoplesoft

MachineB

TRA

CPUMonitor

ProcessEngine 1

TIBCO Adapter forDatabase

MachineA

ProcessEngine 2

TRA

DiskMonitor


Creating a Deployment Configuration | 143

Deployment OverviewDeploying and starting your project involves these major steps:

1. Create the deployment configuration using TIBCO Designer. See Creating a Deployment Configuration on page 143.

2. Send the deployment configuration to the TRA on each machine using the Deploy icon in the TIBCO Designer toolbar. See Sending a Deployment Configuration to the TRA on page 145.

Each TRA uses information stored locally on the machine where it runs. This information includes how to restart the components on that machine and what conditions on the machine to monitor. Do not modify the files that TRA uses to store the deployment configuration.

3. Start the components on each machine. This is either done by rebooting the machine (if the start on reboot option is checked for the component) or by using TIBCO Administrator to start each component. See Starting Deployment Components on page 147.

Creating a Deployment Configuration

You create a deployment configuration as follows:

1. Open your project in TIBCO Designer.

2. With the project selected, open the Deployment palette and drag and drop resources from the Deployment palette into the design panel.

The deployment configuration is a hierarchical set of resources, starting with the Deployment Configuration as the root object. Figure 35 illustrates the relationships between resources in the Deployment palette.



Figure 35 Relationship between deployment resources

Each resource within the Deployment palette is contained within another resource, similar to how folders hold objects in a file system. The deployment configuration is the root object, and there can be only one deployment configuration per project.

The deployment configuration can hold multiple machines. Only machines within the same TIBCO administration domain can be part of the deployment configuration. Each machine can have one or more process engines, adapter instances, or monitoring conditions.

Each process engine or adapter instance can specify actions to perform in the event of a failure. These actions can be either in the Any Failure resource (that is, perform the action for every failure that occurs), or they can be in a specific Component failure event resource (Component failure event resources are specified as First Failure, Second Failure, or Subsequent Failure).

Deployment Configuration

Machine

CPU Monitor

Email

CustomAlert

Process Monitor

Email

CustomAlert

Process Engine

Any Failure

Restart Email

CustomAlert

Recovery

Restart Email

CustomAlert

Adapter Instance

Any Failure

Restart Email

CustomAlert

Recovery

Restart Email

CustomAlert

Disk Monitor

Email

CustomAlert

Each Process Engine resource must be uniquely named across all machines in your deployment configuration. That is, you cannot have two Process Engines with the same name anywhere within a deployment configuration.


Sending a Deployment Configuration to the TRA | 145

Each machine can have any number of monitor resources that specify conditions on the machine to monitor. When the condition is met, you can specify to perform certain actions. For example, if CPU usage goes above 90%, an alert should be sent to the administration server.

The Any Failure or Component failure event resources can also hold the actions to perform in the event of a failure of a process engine or adapter. These actions include restarting the process engine or adapter, sending email to a user, sending an alert to the administration server, or executing an operating system command or script. You can perform more than one of these actions in the event of a failure.

For more information about creating deployment configurations, see TIBCO BusinessWorks Palette Reference.

The TIBCO BusinessWorks Quick Start document steps you through an example of creating a deployment configuration.

Sending a Deployment Configuration to the TRA

Once the deployment configuration is created, you must send it to the TIBCO Runtime Agent (TRA) on each machine within the deployment. TRA stores information about how each component should be started and performs the specified actions if the component experiences a failure.

To send a deployment configuration to TRA, perform the following steps:

1. Open your project using TIBCO Designer.

2. Select the Deployment Configuration in the project panel.

3. Click the Deploy icon in the toolbar.

The deployment dialog appears.



This dialog shows the following information:

— The machines in the deployment configuration.

— The deployment configuration and information about the last time the project was deployed.

4. You can select each machine on which you wish to deploy individually and click the Deploy button, or you may click the Deploy all button to send the configuration to all machines.

5. If the deployment is successful, the TRA stores the information about each component. If the deployment is not successful, errors are listed and must be corrected before deploying.

The Status line indicates whether the current deployment configuration is in sync. If it isn’t, you must undeploy and redeploy the project. If it is, but you’ve made changes to other parts of the project, save your project and restart the component in which the change was made using TIBCO Administrator. You do not need to redeploy the project.

You will see the deployment configuration files within the directory where TRA and TIBCO BusinessWorks are installed. Do not modify these files manually.


Starting Deployment Components | 147

Starting Deployment Components

Once a deployment is sent to the TRA, the components within the deployment are not automatically started on the machine. The component is restarted the next time the machine reboots if you select the corresponding check box in the configuration panel.

If you wish to manually start the component without rebooting the machine, you must use the TIBCO Administrator interface. See TIBCO Administrator User’s Guide for more information about starting and stopping components.

Undeploying

After sending a deployment configuration, you may wish to undeploy the configuration so that you can modify it and redeploy it.

To undeploy a deployment configuration, perform the following steps:

1. Select the Deployment Configuration in the project panel.

2. Click the Deploy icon in the toolbar.

3. The deployment dialog appears. This dialog lists the machines in the deployment configuration. The deployment configuration and information about the last time the project was deployed are listed on the right.

4. Select the machine and the component you wish to undeploy, then click the Undeploy button. Deployment configuration files are removed from the machine for the component and the component will no longer be displayed in the TIBCO Administrator GUI.

If you make changes to deployment configuration data or to component user/password information, you must undeploy and redeploy the project. For all other changes to the project, you only need to save the project and stop and restart the component(s) involved.

When you attempt to undeploy a running component, you are warned that the component is still running.



Controlling Execution of Process Instances

Your system may have limited memory or resources, or you may want to restrict process instances to run sequentially. The Process Engine deployment resource allows you to specify the maximum number of process instances that can concurrently be loaded into memory. You can also specify that once a process instance is loaded, it must remain in memory until it completes.

Process Instances and System ResourcesWhen TIBCO BusinessWorks detects an event that starts a process, the process engine creates a process instance for that event. Process instances consume memory and processing resources on your system. Depending on the resources available, you may only be able to run a limited number of process instances concurrently.

Process instances typically remain in memory as long as they are processing an activity. If the process instance is waiting for an incoming event (for example, the process instance has reached a Wait for Adapter Message activity), it can be paged out to disk and resumed later after the event arrives. New process instances are paged out to disk until there is available memory and resources to process them.

Specifying Maximum Number of Concurrent ProcessesFor any process definition that is listed in the Process Definitions tab of the Process Engine deployment resource, you can specify the maximum number of concurrent process instances by entering a value in the Max Jobs column for that process definition. This value specifies that the process engine can only keep the specified number of process instances in memory before process instances must be paged out to disk.

You can only specify options for process definitions that you load into the process engine resource. That is, if you choose Select All on the Process Definitions tab, you are not able to specify any options for each of the process definitions. If you unselect Select All and then use the Browse button to load specific process definitions, the selected process definitions appear in the list and you can specify options for each process definition.

You can only specify process definitions that contain a process starter (not process definition that begin with a Start activity). All dependent subprocess definitions are automatically loaded, but you cannot specify options for subprocesses.


Controlling Execution of Process Instances | 149

Specifying a value for Max Jobs causes the Process Engine to incur some overhead for managing the paging of process instances to and from disk. If you have sufficient system resources and do not expect incoming events to exceed the limits of your system, you can specify Max Jobs as 0. This allows the process engine to create an unbounded number of process instances and eliminates the overhead of paging.

Keeping Process Instances in MemoryYou specify that once a process instance is loaded into memory, it should not be paged out to disk until it completes. This option is useful if you wish to specify sequential processing of incoming events, or if you want to enforce limited concurrent execution of process instances.

The Activation Limit option is available for any process definition listed in the Process Definitions tab of the Process Engine deployment resource. The Activation Limit and Max Jobs options work together to provide different concurrency limits. The following sections describe the effects of various combinations of these options.

Max Jobs=1 Activation Limit=enabled

This setting ensures sequential processing of incoming events. As an event arrives, the process engine creates a process instance and keeps it in memory. The maximum number of process instances in memory is one, so only one process can execute at a time because the currently loaded process cannot leave memory until it completes. The process engine creates process instances for new incoming events, but pages them to disk immediately until the first process instance completes. Once the process instance completes, the process instance for the second event is processed, and so on.

Max Jobs=n Activation Limit=enabled

This setting ensures a limited amount of concurrent processing. This situation is useful if you have limited resources, such as a limited number of database connections. You can set Max Jobs to a relatively small number and the Activation Limit option keeps the process instances in memory until the process instances complete. Each loaded process uses a resource until the process instance completes. Once a process instance releases the resource, a new process is loaded into memory and uses the resource.

Max Jobs=0 Activation Limit=enabled/disabled

Setting Max Jobs is set to 0 specifies that there is no limit on the number of process instances to keep in memory. In this case, Activation Limit is ignored.



Max Jobs=n Activation Limit=disabled

When Max Jobs is set to any positive integer, this sets the limit for the number of process instances kept in memory. Any number of process instances can exist, but only the amount specified by Max Jobs can be actively processed in memory concurrently. The Activation Limit option is disabled, so new processes or processes that are currently waiting (for example, for a Wait for Adapter message activity) can be paged out of memory once the maximum number is reached. This allows you to have an unlimited number of concurrent process instances, but only the maximum number are in memory and actively processing. Because the Activation Limit option is disabled, there is no guarantee that process instances will complete in the same order as incoming events.

Configuring Storage for Process Engines

You can configure the location where TIBCO BusinessWorks process engines store internal information. Most of the information a process engine stores is information about each process instance’s state when a checkpoint is taken. There is, however, some other internal information stored by the engine. You can specify that this information is stored in the filesystem (the default) or in a database.

For some systems, using a filesystem for process engine storage may be sufficient. However, some functionality is only available when using a database for process engine storage:

• With a database for storage, fault-tolerant engines can recover process instances up to a checkpoint. Without a database, running process instances cannot be recovered to their last checkpoint.

• With a database for storage, Wait/Notify activities can be used to pass data between process instances on different machines. Without a database, the wait and notify activities cannot communicate across machines.

To configure the storage for your process engine, click on the Advanced tab of the process engine in your deployment configuration. The field Check Point Recovery Storage controls the location of process engine storage. The default location for process engine storage is the filesystem.


Configuring Storage for Process Engines | 151

If you wish to specify a database for storage, select the JDBC option in the Check Point Recovery Storage field. You must also configure a JDBC Connection shared configuration resource to connect to the database where you wish to store process engine information. After configuring the JDBC Connection resource, specify the resource in the Select a JDBC Shared Resource field on the Advanced tab of your process engine.

Database Table NamesWhen you specify a database for process engine storage, tables are created in your database. The domain name and deployment ID (assigned by TIBCO BusinessWorks) are used to name the tables to ensure uniqueness of the tables for each domain and each deployment.

Because some databases limit the number and kinds of characters for table names, the domain name can altered before being used in the table name. The first eight characters and the last eight characters of the domain name are taken and any non-legal characters (such as spaces or dashes) are converted to underscores. This creates a sixteen-character unique ID for each domain, provided that the first and last eight characters of all of your domain names are unique.

For example, the following illustrates conversion of domain names. Notice the second and third domain names convert to the same ID. You should avoid this by creating domain names so that the combination of the first and last eight characters are unique.

All table names created by TIBCO BusinessWorks begin with T_<domain-id>_<deploymentID>_. You can alter the storage parameters for these tables if you desire, but the table names and column definitions must remain the same.

Domain Name Converts To Domain ID

TIBCO_domain_Accounting TIBCO_docounting

TIBCO_domain_Marketing TIBCO_doarketing

TIBCO_domain_Direct_Marketing TIBCO_doarketing



Configuring Fault-Tolerant Engines

The TIBCO BusinessWorks process engine can be configured to be fault-tolerant. You can start up several engines, and in the event of a failure, process starters and process instances are restarted by other engines.

If you use a database to store process engine information, a process instance is reinstantiated to the state of its last checkpoint. In the event of a failure, any processing done after a checkpoint is lost when the process instance is restarted by another engine. See TIBCO BusinessWorks Palette Reference for more information about Checkpoint activities. See Configuring Storage for Process Engines on page 150 for more information about configuring process engine storage.

Figure 36 illustrates normal operation of a fault-tolerant configuration. One engine is configured as the master, and it creates and executes process instances. The second engine is a secondary engine, and it stands by in case of failure of the master. The engines send heartbeats to notify each other they are operating normally.

Figure 36 Normal operation: master processing while secondary stands by

In the event the master process engine fails, the secondary engine detects the stop in the master’s heartbeat and resumes operation in place of the master. All process starters are restarted on the secondary, and process instances are restarted to the state of their last checkpoint. Figure 37 illustrates a failure and the secondary restarting the process instances.

TIBCO BusinessWorksProcess Engine 2

ProcessDefinition

ConfigurationsStandby


PI3

PI2

PI1

ProcessDefinition

Configurations

heartbeat


Configuring Fault-Tolerant Engines | 153

Figure 37 Fault-tolerant failover

The expected deployment is for master and secondary engines to reside on separate machines. You can have multiple secondary engines, if desired, and you can specify a weight for each engine. The weight determines the type of relationship between the fault-tolerant engines. See Peer or Master and Secondary Relationships on page 153 for more information about relationships between fault-tolerant engines.

A master and its secondary engines is known as a fault-tolerant group. The group can be configured with several advanced configuration options, such as the heartbeat interval and the weight of each group member. See TIBCO BusinessWorks Palette Reference for a complete description of configuration options for fault tolerance.

Peer or Master and Secondary RelationshipsMembers of a fault-tolerant group can be configured as peers or as master and secondary engines. If all engines are peers, when the machine containing the currently active process engine fails, another peer process engine resumes processing for the first engine, and continues processing until its machine fails.

If the engines are configured as master and secondary, the secondary engine resumes processing when the master fails. The secondary engine continues processing until the master recovers. Once the master recovers, the secondary engine shuts down and the master takes over processing again.

The Fault Tolerance tab of the Process Engine deployment resource allows you to specify the member weight of each member of a fault-tolerant group. The member with the highest weight is the master. You can select "Peer" in the first field on the tab to configure all engines as peers (that is, they all have the same weight). You can select Primary/Secondary to configure the engines as master and secondary. You can also select Custom to specify your own values for the weight of each member of the group.


PI3

PI2

PI1

ProcessDefinition

Configurations


PI3

PI2

PI1

ProcessDefinition

Configurations



Failover and Checkpoint DataA checkpoint saves the current state of a running process instance. In order for a secondary process engine to resume running process instances from their last checkpoint, the secondary process engine must have access to the saved state of the process instances from the master process engine.

The Advanced tab of the Process Engine deployment configuration resource contains a field named Check Point Recovery. This field specifies where the state of process instances is stored when a checkpoint is performed. This field can specify the information should be saved either to a filesystem or to a database.

Because fault-tolerant engines are expected to be on separate machines, you should specify JDBC in the Check Point Recovery field of the Advanced tab for each process engine. This allows you to specify the same JDBC Connection resource for the master and secondary engines, and therefore all engines can share the information stored for process instance checkpoints.

If all engines share the checkpoint information, then the secondary engines can recover process instances up to their last checkpoint. If engines do not share the checkpoint information, process instances are not restarted.

Process Starters and Fault-ToleranceWhen a master process engine fails, its process starters are restarted on the secondary engine. This may not be possible with all process starters. For example, the HTTP Receiver process starter listens for HTTP requests on a specified port on the machine where the process engine resides. If a secondary engine resumes operation for a master engine, the new machine is now listening for HTTP requests on the specified port. HTTP requests always specify the machine name, so incoming HTTP requests will not automatically be redirected to the new machine.

Each process starter has different configuration requirements, and not all process starters may gracefully resume on a different machine. You may have to provide additional hardware or software to redirect the incoming events to the appropriate place in the event of a failure.

Also, your servers may not have all of the necessary software for restarting all of instances. For example, your database may reside on the same machine as your master process engine. If that server goes down, any JDBC activities will not be able to execute. Therefore, you may not wish to load process definitions that use JDBC activities in your secondary process engine.

You can specify that your secondary process engine loads different process definitions than the master. You may only want to load the process definitions that can gracefully migrate to a new server during a failure.


| 155

Appendix A Predefined Global Variables

The following table lists and explains the predefined global variables. Some global variables are automatically used within the system when an adapter configuration is defined. For example, the RV Session shown above uses the value defined for the RvService, RvNetwork and RvDaemon global variables.

Variable Description

Deployment Defaults to the TIBCO Designer project name. This value can be any string value. This global variable is used by the system to partially define the subject name defined for a service.

DirLedger Used by the system when defining the path name of the TIBCO Rendezvous certified messaging ledger file. The default is root installation directory.

DirTrace Used by the system to partially create the path name for log file used by the adapter. The default is the root installation directory.

Domain The default value for file-based local projects is MyDomain. The value for server-based projects is the domain to which the project was saved.

Env Included for backward compatibility. Do not use.

HawkEnabled Used by the system to indicate whether TIBCO Hawk is used to monitor the adapter. True indicates that a Hawk microagent is defined for the adapter. False indicates the microagent is not to be used. Default is False.

RemoteRvDaemon Used by the system to identify the TIBCO Rendezvous routing daemon. See TIBCO Rendezvous Administration for details about specifying the routing daemon name.


156 | Appendix A Predefined Global Variables

RvDaemon Used by the system to identify the TIBCO Rendezvous daemon parameter. The parameter instructs the transport object about how and where to find the Rendezvous daemon and establish communication. The default value is 7500, which is the default value used by the Rendezvous daemon. See TIBCO Rendezvous Concepts for details about specifying the daemon parameter.

RvNetwork Used by the system to identify the TIBCO Rendezvous network parameter. Every network transport communicates with other transports over a single network interface. On computers with more than one network interface, the network parameter instructs the TIBCO Rendezvous daemon to use a particular network for all outbound messages from this transport. See TIBCO Rendezvous Concepts for details about specifying the network parameter.

RvService Used by the system to identify the TIBCO Rendezvous service parameter. The Rendezvous daemon divides the network into logical partitions. Each transport communicates on a single service; a transport can communicate only with other transports on the same service. See TIBCO Rendezvous Concepts for details about specifying the service parameter.

Default is 7500

RvaHost Used by the system to identify the computer on which the TIBCO Rendezvous agent runs. See TIBCO Rendezvous Administration for details about specifying the rva parameters.

RvaPort Used by the system to identify the TIBCO Rendezvous agent TCP port where the agent listens for client connection requests. See TIBCO Rendezvous Administration for details about specifying the rva parameters.

Defaults to 7501.

TIBHawkDaemon Used by the system to identify the TIBCO Hawk daemon parameter. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.



Predefined Global Variables | 157

TIBHawkNetwork Used by the system to identify the TIBCO Hawk network parameter. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.

TIBHawkService Used by the system to identify the TIBCO service parameter. See the TIBCO Hawk Installation and Configuration manual for details about this parameter.



158 | Appendix A Predefined Global Variables


| 159

Index

Symbols

$_error process variable 114

A

activities 36, 44creating groups 68End 59Input tab icons 83mapping input 88not-useful mappings 96Start 58stepping through when testing 135ungrouping 68

adapter resourcesadding 25

adding adapter resources 25addressing schema elements 106

B

breakpoints 131icon when set 132

business processes 32

C

Call Process activity 39category mode 10checkpoints

database storage 150failover and 154

fault-tolerance 152choose statements 99clearing breakpoints 131colors used when testing process definitions 135combining projects 25components

starting and stopping 147concurrent process isntances

maximum 148conditions 64constants in XPath 87controlling memory usage 148creating

custom palettes 12deployment configuration 143groups 68process definitions 40projects 16transitions 63

custom palettes 12customer support xv

D

datasent across process instances 122, 123

database storage 150fault-tolerance and 152inter-process communication 125table names 151

debugging 129, 130breakpoints 131icons 137

deployment configurationcreating 143illustrated 142implementing 143


160 | Index

overview 142sending to TRA 145starting and stopping components 147

E

edit custom palette 12effects of mapping 90End activity 59

process error schemas 117enforcing order of execution 126enterprise computing 32error handling 113

error propagation 115no-action groups 72overview 114process error schemas 117repeat on error until true group 78

evaluation context 107and mapping 89

examplesinter-process communication 125

export resource 26

F

failovercheckpoint data 154

fault-tolerance 152master 153peers 153process starters 154secondary 153

G

Generate Error activityerror propagation 115process error schemas 117

global variables 27predefined 155

groups 38, 68creating 68error propagation 115loops 73

accumulate output 74index variable 74

no action 72transaction 73ungroupping 68

H

handling errors 113

I

iconstest mode 137

If statements 98implementing a deployment configuration 143import project 24import resource 26incoming events

key 49scalability 127timeout 49

index variable 74Input tab

icons 83inter-process communication 121

database storage 125, 150examples 125overview 122timeout 124

iterate loop 75


Index | 161

K

keyincoming event 49used for inter-process communication 122, 124

L

list statements 100loops 73

accumulate output 74index variable 74iterate 75repeat on error until true 78repeat until true 76

M

machinesfault-tolerance 152

main window 5mapping 81, 82, 88

activity input 88addressing schema elements 106branch to branch 92choose statements 99effects of different mappings 90if statements 98Input tab icons 83list statements 100modify statement 97non-repeating to repeating 94non-useful mappings 96repeating to non-repeating 95repeating to repeating 95set substitution 102simple element to simple element 92transforming data 97XPath operators and functions 111

master process engnie 153memory usage 148

modify statement 97multiple events resuming a running process

instance 126

N

no action groups 72Notify activity 122Notify Configuration shared configuration 123

O

opening projects 22

P

palette mode 10palettes 7

closing 12custom 12

pinning process instances in memory 149preferences 10primary process engine 153process definitions 35

breakpoints 131breakpoints for testing 131conditions 64creating 40creating transitions 63debugging 129, 130effects of different mappings 90grouping activities 68handling errors 113index variable in loops 74new 36process error schemas 117process starters 56process variables 54propagating errors 115


162 | Index

scalability and incoming events 127stepping through to test 135subprocesses 39test window 132testing 130transaction groups 73transforming data 97ungroupping activities 68

process enginesdatabase storage 150database table names 151in operation 35

process instancescommunicating 122controlling memory usage 148enforcing order of execution 126fault-tolerance 152maximum concurrent 148multiple events resumnig 126when testing 133

process modeling 32process starters 56

fault-tolerance 154process variables 54

$_error 114processes 34project store 19project templates 16projects 6

adding adapter resources 25combining 25importing 24opening 22saving 18Storage tab 19undeploying 147

propagation of errors 115

R

Receive Notification activity 122repeat on error until true loop 78repeat until true loop 76

resources 6exporting 26importing 26

S

save project options 16saving project as template 19saving projects 18scalability

incoming events 127schema elements 82

addressing 106schemas

process error schemas 117search predicates in XPath expressions 108secondary process engine 153

process starters 154semaphores 122sending deployment configuration to TRA 145set substitution 102setting a breakpoint 132setting breakpoints 131setting which palettes display 12shared configuration 38specifying constants in XPath expressions 87Start activity 58

subprocesses 39starting

deployment components 147process instances 56TIBCO Designer 2

startup options 2Storage tab 19subprocesses 39

Call Process activity 39error propagation 116illustrated 40

support, contacting xvsystem resources, controlling 148


Index | 163

T

tables in database 151technical support xvtemplates 16, 19test mode 129testing process definitions 129, 130

breakpoint locations 131colors in test mode 135menus and toolbar icons 137overview 130process instances 133stepping through activities 135test window 132

TIBCO Designer 2implementing a deployment configuration 143roadmap 4

TIBCO Runtime Agent (TRA)sending deployment configuration 145

timeoutincoming events 49inter-process communication 124

transaction groups 73transforming data 82, 97transitions 37, 62

conditions 64creating 63

U

undeploying projects 147ungrouping 68

V

variables, process 54

W

Wait activity 122waiting for incoming events 49

X

XPath 105basics 106conditions 64editor 108evaluation context 89, 107example 111operators and functions 111search predicates 108specifying constants 87


164 | Index


Date post:	18-Nov-2014
Category:	Documents
Upload:	naveen
View:	106 times
Download:	1 times