Business Studio Customization

TIBCO Business Studio™

CustomizationSoftware Release 2.0July 2007

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 TIBCO BUSINESS STUDIO INSTALLATION GUIDE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. 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.TIB, TIBCO, TIBCO Software, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO Business Studio and TIBCO iProcess are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, 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 SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. PLEASE SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.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.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 2004-2007 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

Contents | i

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

How to Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv

Target Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viTIBCO Business Studio Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Implementing Business Process Integration (Import) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Exporting from TIBCO Business Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2 Understanding the File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

XPDL 2.0 Schema Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Execution Details of a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Setting the Destination Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Visual Characteristics of a Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13NodeGraphicsInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13ConnectorGraphicsInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

References Between Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Schema Extensions for Service Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Simulation Schema Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Activity Parameters (ActivitySimulationData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Participant Parameters (ParticipantSimulationData). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Sequence Flow Splits (SplitSimulationData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Simulation Start Parameters (StartSimulationData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Sequence Flow Parameters (TransitionSimulationData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Parameter Distribution (WorkflowProcessSimulationData). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 3 Writing an Import/Export Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Creating a New Import/Export Wizard Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

TIBCO Business Studio Customization

ii | Contents

Chapter 4 Deployment Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Implementing Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Define the Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Define the Management Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Defining the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Define the Possible Server Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Define States for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Configuring the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Define the Deployment Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Tutorial - Deployment to a WebDAV Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Creating a WebDAV Server Type Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Creating the Server Type Connection Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Connecting to WebDAV server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Providing Server Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Deploying Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Implementing Operations for ServerElements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58


| iii

Preface

TIBCO Business Studio™ is used to model, simulate and implement business processes. This guide describes the areas of TIBCO Business Studio that can be customized or extended.

Topics

• How to Use This Guide, page iv

• How to Contact TIBCO Support, page viii


iv | How to Use This Guide

How to Use This Guide

This guide contains the following chapters:

• Chapter 1, Overview - describes how to use this guide to achieve your specific goal.

• Chapter 2, Understanding the File Format - describes how XPDL2 is used by TIBCO Business Studio, as well as the extensions provided.

• Chapter 3, Writing an Import/Export Wizard - describes how to write a wizard to either import a custom file format into TIBCO Business Studio or export a TIBCO Business Studio Process to a custom format.

• Chapter 4, Deployment Framework - describes how to use the Deployment Framework to remotely deploy your own artifact (Module) on a remote server using TIBCO Business Studio. It also includes a tutorial on deploying to a Web-based Distributed Authoring and Versioning (WebDAV) server.


Preface | v

Target Audience

This guide is aimed at systems integrators and developers who want to integrate TIBCO Business Studio with other applications upstream in the product lifecycle.

This guide assumes that you are familiar with the schema of the application whose procedures you want to import into TIBCO Business Studio as well as with Extensible Stylesheet Language Transformations (XSLT).

Java programming and Eclipse experience is required if you want to contribute features to TIBCO Business Studio, extend the Validation Framework, or use the Deployment Framework.


vi | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Business Studio DocumentationThe following documents form the TIBCO Business Studio documentation set:

The TIBCO Business Studio documentation set consists of:

• TIBCO Business Studio Modeling User’s Guide: Read this manual to learn how to model business processes.

• TIBCO Business Studio Simulation User’s Guide: Read this manual to learn how to use the simulation features of TIBCO Business Studio.

• TIBCO Business Studio Process Developer’s Guide: Read this manual to learn how to elaborate a Process with execution details and deploy it to a runtime platform.

• TIBCO Business Studio Installation Guide: Read this manual for instructions on site preparation and installation.

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


Preface | vii

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO BusinessWorks Concepts.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.


viii | How to Contact TIBCO Support

How to Contact TIBCO Support

The community edition of TIBCO Business Studio is unsupported. For self-service support, education, and access to the TIBCO Developer Network, visit http://www.tibco.com/devnet/index.html.

If you have purchased another TIBCO product that includes support for TIBCO Business Studio and have comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support/

• If you already have a valid maintenance or support contract, visit this site:

http://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one.


http://www.tibco.com/devnet/index.html

http://www.tibco.com/services/support/

http://support.tibco.com

| 1

Chapter 1 Overview

This chapter describes how to use the information in the rest of this guide.

Topics

• Implementing Business Process Integration (Import), page 2

• Exporting from TIBCO Business Studio, page 3


2 | Chapter 1 Overview

Implementing Business Process Integration (Import)

Scenario TIBCO Business Studio is not yet the primary corporate modeling tool.

Goal To leverage the investment in the current Business Process Analysis (BPA) tool by importing existing processes into TIBCO Business Studio and getting the Processes into an executable form.

Approach To import a process from an established BPA tool into TIBCO Business Studio, you must do the following:

1. Study the selected BPA tool, particularly the XML export facility.

2. Identify the significant elements in the BPA tool’s XML format.

3. Referring to Understanding the File Format, familiarize yourself with the XPDL format and the TIBCO extensions.

4. Construct a mapping table (for example, a spreadsheet) between the interesting elements. This will be the basis of the XSLT that will transform elements from the BPA XML output into XPDL that can be imported into TIBCO Business Studio.

5. Implement the mapping in XSLT.

6. Register the XSLT as a plug-in that may be distributed to all users (by copying to the plugins directory) or installed directly. See Writing an Import/Export Wizard on page 31.

For an example of a mapping XSLT, navigate to eclipse\plugins sub-directory of your Eclipse installation. Using WinZip, open the file com.tibco.xpd.aris_x.y.z. This archive contains a file called ARISXML_2_XPDL2.xslt that contains the mappings that TIBCO Business Studio uses for the import of Aris models.


Exporting from TIBCO Business Studio | 3

Exporting from TIBCO Business Studio

Scenario Application developer or systems integrator wants to take output from TIBCO Business Studio and embed it within a custom BPM solution (for example, create a JSP web page for each User Activity).

Goal Transform part or all of the process into supporting artifacts in the final solution (for example, JSP forms, portal pages and document management systems).

Approach To export Process information from TIBCO Business Studio to another application:

1. Referring to Understanding the File Format on page 5, familiarize yourself with the XPDL format and the TIBCO extensions.

2. Study the required output. For example, in the case of JSP forms, suppose that for each User Activity in the Process, the desired output is a default form with a field for each Parameter of the User Activity.

3. Construct a mapping table (for example, a spreadsheet) between the significant TIBCO Business Studio XPDL elements and their target objects (be they XML objects or widgets in a GUI toolkit).

4. Implement the mapping in XSLT.

5. (Optional) Document any restrictions on creating the output (such as the JSP form generator supporting only simple data field types).


4 | Chapter 1 Overview


| 5

Chapter 2 Understanding the File Format

The TIBCO Business Studio Package file uses the following schemas:

• XPDL Version 2.0

• XPDL Version 1.0 (Internally, for direct deployment to the TIBCO iProcess Engine)

• Extensions schema - process-related XPDL extensions

• Simulation schema - XPDL extensions to support the simulation of Processes

• Various extension schemas, each describing meta-data for one or more sub-types of service task.

This chapter describes the Extensions and Simulation schemas used by TIBCO Business Studio.

Topics

• XPDL 2.0 Schema Overview, page 6

• Execution Details of a Package, page 11

• Visual Characteristics of a Package, page 13

• Schema Extensions for Service Tasks, page 19

• Simulation Schema Overview, page 20

To import a file, only the correct XPDL and Extensions semantics are required; simulation is optional and default simulation parameters can be added by TIBCO Business Studio once the Process has been imported.


6 | Chapter 2 Understanding the File Format

XPDL 2.0 Schema Overview

The XPDL Version 2.0 schema provides all the elements needed to execute a process as well as the visual elements necessary to view a process in TIBCO Business Studio. The following series of diagrams show the relationship between the BPMN elements in TIBCO Business Studio and their mapping to the XPDL schema.

For more information, see:

• XPDL - http://www.wfmc.org/standards/xpdl.htm

• BPMN - http://www.bpmn.org/


http://www.wfmc.org/standards/xpdl.htm

http://www.bpmn.org/

XPDL 2.0 Schema Overview | 7

Process Flow Objects

This diagram shows the major Process Flow Objects (Package, Process, Activity and Transitions), excluding the visual objects such as Pools, Lanes.



Artifacts

XPDL Artifacts belong to the Package and are referred to in a Process by Lanes and Pools. This diagram shows the relationship of Artifacts to other objects:


XPDL 2.0 Schema Overview | 9

Associations

This diagram shows how optional Associations are made between non-flow objects (such as a Text Annotation) and flow objects or flows:

Message Flow

Message Flow can connect objects in different Pools or objects in one Pool with the boundary of another Pool. The following diagram shows Message Flow:



Data Fields, Formal Parameters, Participants, and Type Declarations

Data Fields and Participants can be scoped in that they can be created at the Process level or at the Package level (if you want to share them amongst Processes). Formal Parameters can only be created at the Process level and Type Declarations can only be created at the Package level. The following diagram shows the relationship of Data Fields, Formal Parameters, Participants, and Type Declarations to Pools, Process, and Package.

The relationship of a Participant to a Pool is denoted in BPMN, but neither required nor enforced by TIBCO Business Studio.


Execution Details of a Package | 11

Execution Details of a Package

This section describes the parts of the XPDL Package file that must be present if you want to execute a TIBCO Business Studio XPDL package/process in iProcess Engine. It does not cover visual aspects of a Process (see Visual Characteristics of a Package on page 13).

Creating a PackageThe root XPDL element is Package and the following namespaces are used:

A Package Header in TIBCO Business Studio is defined by XPDL as follows:

TIBCO Business Studio contributes the following elements to the Package only:

The semantics for the Package, Process and Redefineable Headers allow the least restrictive interpretation of the XPDL schema possible.

These are elements called ExtendedAttribute that are in the base namespace and should not be confused with extended namespaces such as the following:

<xpdl2:Task> <xpdl2:TaskService xpdExt:ImplementationType="E-Mail"

xpdl2:Implementation="Other"> <xpdl2:MessageIn Id="_V_wdICrAEdy4JvZXy-dYnw"/> <xpdl2:MessageOut Id="_V_wdISrAEdy4JvZXy-dYnw"/> <email:Email> <email:Definition> <email:From email:Configuration="Server"/> <email:To>[email protected]</email:To> <email:Subject>RE: minutes of our

meeting</email:Subject> </email:Definition> <email:SMTP email:Configuration="Server"/> </email:Email> </xpdl2:TaskService> </xpdl2:Task>



Setting the Destination EnvironmentSetting the destination environment on a Process controls the validation that is performed on that Process and also, in the case of simulation, what simulation parameters are associated with the Process. You can specify multiple destination environments. The following example shows the XPDL for a Process intended for simulation:<xpdl2:ExtendedAttribute Name="Destination"

Value="simulation1.2"/>

Attribute Example Notes

CreatedBy <xpdl2:ExtendedAttribute Name="CreatedBy" Value="TIBCO Business Studio"/>

You can provide any value. The example indicates that the Process was created in TIBCO Business Studio, but there is no checking or validation.

FormatVersion <xpdl2:ExtendedAttribute Name="FormatVersion" Value="3"/>

Mandatory. This must be set to 3. If this value is missing, the TIBCO Business Studio will attempt to validate/add required visual extensions to the XPDL. This process may not be successful.

Value Description

ipm10.x Specifies that the Process is validated for export to the TIBCO iProcess Modeler.

ipe10.x Specifies that the Process is validated for direct deployment to the TIBCO iProcess Engine.

simulation1.2 Specifies that the Process is validated for simulation.


Visual Characteristics of a Package | 13

Visual Characteristics of a Package

This section describes how the visual characteristics of a Package/Process are created. This would be important for example, if you have your own XPDL that you want to import and display in TIBCO Business Studio.

NodeGraphicsInfoThis XPDL2 element stores graphical information (for example, color, size, and so on) about visual objects, except for connecting lines (see ConnectorGraphicsInfo on page 15).

The following table describes the standard Attributes/Elements of NodeGraphicsInfo.

Attribute/Element Description

ToolId For all standard NodeGraphicsInfo elements this is XPD. For special purpose NodeGraphicsInfo elements, ToolId is extended for different purposes (for example, XPD.BorderEventPosition). For more information, see Special Purpose NodeGraphicsInfo Elements on page 15.

BorderColor, FillColor String containing three comma-separated numeric values representing Red, Green, Blue values for the color (each between 0 and 255). For example, 255,0,0 (bright red), 0,0,0 (black), and so on.

Height, Width Height and width of the object in pixels.

• Width is never specified for a Lane (this is calculated automatically from its content).

• Width and Height are never specified for a Pool (these are calculated automatically from its content).

• Height is always calculated automatically for diagram notes. If width is present for diagram note, text is wrapped at the specified width; if not present, width is set automatically.



Coordinates XCoordinate and YCoordinate specify the pixel location of the center of the object.

Notes:

• Intermediate Events that are attached to a Task boundary should be specified as 0.0.

• For Text Annotations (Diagram Notes), these coordinates define the center of the the left hand edge.

LaneId XPDL is not specific about the requirements for various BPMN concepts. Therefore, LaneId is dependent on object type.

TIBCO Business Studio specifies the LaneId value as follows

• Activities in a Lane - The parent LaneId.

• Activities in an Embedded Sub-Process - LaneId not set.

• Artifacts in a Lane – The parent LaneId.

• Artifacts in an Embedded Sub-Process - The activity set Id for the Embedded Sub-Process.

IsVisible For Lanes only:

• false – Lane is closed

• true – Lane is open (default if not present).




Special Purpose NodeGraphicsInfo Elements

In addition to the standard NodeGraphicsInfo elements listed in the previous table, the following special purpose NodeGraphicsInfo element is used when extra graphical information does not fit into the single standard NodeGraphicsInfo element for an object. These are distinguished from the standard NodeGraphicsInfo elements by their extended ToolId value.

ConnectorGraphicsInfoThis XPDL2 element stores graphical information about connection lines such as Transition (Sequence Flows), MessageFlow and Association. The following table describes the standard Attributes/Elements of ConnectorGraphicsInfo.

ToolId Description

XPD.BorderEventPosition An Intermediate Event on a Task boundary is specified as a percentage of distance around the parent task’s boundary line (going clockwise from top right corner).

This distance is specified in the Coordinates/XCoordinate attribute as a floating point number.


ToolId For all standard ConnectorGraphicsInfo elements this is XPD. For special purpose ConnectorGraphicsInfo elements, ToolId is extended to for different purposes (for example, XPD.LabelAnchorPosition). For more information, see Special Purpose ConnectorGraphicsInfo Elements on page 16.

Border Color Specifies the connection line color as a string containing three comma-separated numeric values representing Red, Green, Blue values for the color (each between 0 and 255). For example, 255,0,0 (bright red), 0,0,0 (black), and so on.



Special Purpose ConnectorGraphicsInfo Elements

In addition to the standard ConnectorGraphicsInfo elements listed in the previous table, the following special purpose ConnectorGraphicsInfo elements are used for extra graphical information that does not fit into the single standard ConnectorGraphicsInfo element for an object. These are distinguished from the standard ConnectorGraphicsInfo elements by their extended ToolId value.

ToolId Description

XPD.StartAnchorPosition Specifies a fixed position on a source object’s boundary for the connection line to start.

The actual position is stored in the Coordinate/XCoordinate attribute.

The value of this depends on the source object type:

• Pool (Message Flows only) - The offset, in pixels, from the left hand edge of the Pool.

• Connection (Associations only) - The percentage of total length distance from start of the connection line.

• Other Objects - The percentage distance around the object’s boundary. This is always clockwise, starting from point dependent on the object type:

— Task – Top right corner.

— Event – Right hand side (middle).

— Gateway – Top (middle).

— Data Object – Bottom left corner.

— Diagram Note – Top left corner.

XPD.EndAnchorPosition Specifies a fixed position on target object’s boundary for the connection line to end.

The actual position is stored in the Coordinate/XCoordinate attribute. The value of this is as for the XPD.StartAnchorPosition detailed above.



XPD.LabelAnchorPosition Specifies the anchor position for a connection’s label in relation to the connection line itself as two Coordinate elements.

• The first Coordinate specifies the anchor point of the label as a percentage distance along connection line (from start of connection) in the XCoordinate attribute.

• The second Coordinate specifies a horizontal and vertical offset from the anchor position (in the XCoordinate and YCoordinate attributes).

XPD.LabelSize XCoordinate=Width, YCoordinate=Height. If text wrapped at the given width is too large for the height, the height is automatically adjusted on screen.

ToolId Description



References Between Elements

This section describes the values that TIBCO Business Studio specifies for various standard XPDL2 cross references between elements.

Element Cross Reference Value

Reference Task A reference task references the target task using the target task’s Activity/Id attribute.

Intermediate Link Event The source of the Link Event pair specifies the Activity/Id attribute of the target event, and the Process reference is WorkflowProcess Id of the target event’s parent Process.

The target Link Event specifies its own TriggerResultLink/LinkId attribute as 0, process is always -unknown-.

Activity Performers (Task Participants)

Activity performers are references to the Ids of Participants, Performer type Data Fields, or Performer type Formal Parameters.

Data Fields / Formal Parameters

All references to Data Fields and Formal Parameters (except from Activity Performers), use the name of the Field or Parameter.

Type Declarations References are from Data Field / Formal Parameter by the Type Declaration’s Id.

Processes Inter-Process references (for example from Sub-Process Call Tasks) use the Process Id. References to a Process in another Package use the XPDL filename of the Package (without the .xpdl extension).


Schema Extensions for Service Tasks | 19

Schema Extensions for Service Tasks

TIBCO Business Studio uses the standard XPDL 2.0 schema with extensions for the following types of Service Tasks. You can view HTML documentation of the extension schemas and the actual XSD files for the Service Task types by clicking the following links:

• Database HTML

• Database XSD

• Email HTML

• Email XSD

• Java HTML

• Java XSD

All other types of Service Task (for example, a web services Service Task) conform to the base XPDL 2.0 schema.

If the following documents do not open, check the security settings of your browser.


Schemas/Database/Database.html

Schemas/Email/Email.html

Schemas/Java/Java.html

Schemas/Database/Database.xsd

Schemas/Email/Email.xsd

Schemas/Java/eaijava.xsd


Simulation Schema Overview

When you import a Process into TIBCO Business Studio and with Simulation as the Destination Environment, default simulation parameters are added for Simulation. If you want to over-ride any default simulation parameters, use the simulation schema extensions as described in this section. You can view HTML documentation for the simulation schema extensions and also actual schema by clicking the following links:

• Simulation HTML

• Simulation XSD

ImplementationThe Activity child Implementation and its child (No) must be present for simulation (there is no impact on modelling). For example:

<xpdl:Implementation><xpdl:No/>

</xpdl:Implementation>

Activity Parameters (ActivitySimulationData)This section describes the extensions that allow you to specify simulation data for Activities:


Schemas/Simulation/Simulation.html

Schemas/Simulation/SimulationExtensions11.xsd

Simulation Schema Overview | 21

Specifying Duration Distributions

The following allows you to specify either basic distribution types (where the Activity duration is defined by a mathematical distribution) or a Parameter-based distribution (where imported Parameters are used):

For basic distributions, you can specify the following types:


ConstantRealDistribution

<simulation:ConstantRealDistribution ConstantValue="5.0"/>

Specify a decimal value for ConstantValue.

UniformRealDistribution

<simulation:UniformRealDistribution LowerBorder="2.0" UpperBorder="5.0"/>

Specify decimal values for LowerBorder and UpperBorder.

NormalRealDistribution

<simulation:NormalRealDistribution Mean="5.0" StandardDeviation="2.0"/>

Specify a decimal value for the Mean and StandardDeviation.

ExponentialRealDistribution

<simulation:ExponentialRealDistribution Mean="5.0"/>

Specify a decimal value for Mean.



Parameter-based distributions allow you to specify a distribution for each parameter. For example:

In this example, three different distributions are specified, depending on whether the customer is new or existing; all other values are handled by the default.

Specifying the Time Unit

The time unit specifies the time unit that is used for display purposes in the TIBCO Business Studio user interface. All values for time units (with the exception of SLA information) are stored in the XPDL in minutes. They are then displayed in the user interface in the unit you specify for TimeDisplayUnit.

Example

<simulation:TimeDisplayUnit>HOUR</simulation:TimeDisplayUnit>

Valid values include YEAR, MONTH, DAY, HOUR, MINUTE, and SECOND.

This section specifies the distribution for the default case

This section specifies the distribution for new customers (ExistingCustomer=No)

This section specifies the distribution for existing customers (ExistingCustomer=Yes)

You must specify a default distribution to handle parameters with values other than the ones you explicitly specify.



Adding a Looping Control Strategy

A looping control strategy provides the Simulation engine with the necessary mechanism to break out of loops:

MaxLoopCountStrategy

This strategy allows Sequence Flow to traverse a loop up to the specified maximum number of times.

<simulation:LoopControl><simulation:MaxLoopCountStrategy>

<simulation:DecisionActivity>5</simulation:DecisionActivity><simulation:ToActivity>8</simulation:ToActivity><simulation:MaxLoopCount>5</simulation:MaxLoopCount>

</simulation:MaxLoopCountStrategy></simulation:LoopControl>

NormalDistributionStrategy

This strategy allows Sequence Flow to traverse a loop based on a normal distribution of times (which you specify by providing the mean and standard deviation).

Attribute Notes

DecisionActivity Specifies the Activity that will be used to decide whether to end the loop.

ToActivity Specifies the Activity to proceed with once the loop is finished.

MaxLoopCount Specifies the maximum number of times that the loop should be followed.



<simulation:LoopControl><simulation:NormalDistributionStrategy>

<simulation:DecisionActivity>5</simulation:DecisionActivity><simulation:ToActivity>8</simulation:ToActivity><simulation:Mean>2.0</simulation:Mean><simulation:StandardDeviation>0.5</simulation:StandardDeviation>

</simulation:NormalDistributionStrategy></simulation:LoopControl>

MaxElapseTimeStrategy

This strategy allows Sequence Flow to traverse a loop for an elapsed period of time.

<simulation:LoopControl><simulation:MaxElapseTimeStrategy>

<simulation:DecisionActivity>5</simulation:DecisionActivity><simulation:ToActivity>8</simulation:ToActivity><simulation:DisplayTimeUnit>MINUTE</simulation:DisplayTimeUnit><simulation:MaxElapseTime>10.0</simulation:MaxElapseTime>

</simulation:MaxElapseTimeStrategy></simulation:LoopControl>

Attribute Notes



Mean Specifies the mean used to construct the normal distribution.

StandardDeviation Specifies the standard deviation used to construct the normal distribution.

Attribute Notes





Adding SLA Information

This specifies the maximum amount of delay permissible on the Activity:

<xpdl:ExtendedAttribute Name="ActivitySimulationData"><simulation:ActivitySimulationData SlaMaximumDelay="3.0">

The unit used for SlaMaximumDelay is specified using TimeDisplayUnit (see Specifying the Time Unit on page 22).

Participant Parameters (ParticipantSimulationData)This allows you to specify the information about the Participant that is necessary for simulation (instances, cost, SLA information and so on).

DisplayTimeUnit Specifies the unit in which the elapsed time is measured. Valid values include YEAR, MONTH, DAY, HOUR, MINUTE, and SECOND.

MaxElapseTime Specifies the elapsed time in which you want the loop to finish.

Attribute Notes



<xpdl:Participants><xpdl:Participant Id="1" Name="Call Center Operator">

<xpdl:ParticipantType Type="ROLE"/><xpdl:ExtendedAttributes>

<xpdl:ExtendedAttribute Name="ParticipantSimulationData"><simulation:ParticipantSimulationData SlaMaximumUtilisation="95.0">

<simulation:Instances>3</simulation:Instances><simulation:TimeUnitCost>

<simulation:Cost>0.125</simulation:Cost><simulation:TimeDisplayUnit>HOUR</simulation:TimeDisplayUnit>

</simulation:TimeUnitCost></simulation:ParticipantSimulationData></xpdl:ExtendedAttribute>

</xpdl:ExtendedAttributes></xpdl:Participant>


Instances <simulation:Instances>1</simulation:Instances>

Specifies the number of Participants.

TimeUnitCost <simulation:TimeUnitCost><simulation:Cost>0.8333333333333334</simulation:Cost><simulation:TimeDisplayUnit>HOUR</simulation:TimeDisplayUnit></simulation:TimeUnitCost>

Specifies the cost and time unit used for the Participant in simulation.

SlaMinimumUtilisation <xpdl:ExtendedAttribute Name="ParticipantSimulationData"><simulation:ParticipantSimulationData SlaMinimumUtilisation="65.0" SlaMaximumUtilisation="85.0">

Specifies the minimum utilization percent for the Participant. This is displayed visually when the Process is simulated.

SlaMaximumUtilisation see SlaMinimumUtilisation example Specifies the maximum utilization percent for the Participant. This is displayed visually when the Process is simulated.



Sequence Flow Splits (SplitSimulationData)This specifies the Parameter that is used to distribute Sequence Flow through a split. For example:

SplitSimulationData specifies the Parameter associated with the Gateway (in this case isPaperworkCorrect):

<xpdl:ExtendedAttribute Name="SplitSimulationData"><simulation:SplitSimulationData>

<simulation:ParameterDeterminedSplit>true</simulation:ParameterDeterminedSplit>

<simulation:SplitParameter ParameterId="isPaperworkCorrect"/></simulation:SplitSimulationData></xpdl:ExtendedAttribute>

Simulation Start Parameters (StartSimulationData)This provides the start parameters needed for simulation such as the distribution and number of cases. These are found on the Properties view of the Start Event:

<xpdl:ExtendedAttribute Name="StartSimulationData"><simulation:StartSimulationData NumberOfCases="100">

<simulation:Duration><simulation:ConstantRealDistribution ConstantValue="5.0"/>

</simulation:Duration>



<simulation:DisplayTimeUnit>MINUTE</simulation:DisplayTimeUnit>

</simulation:StartSimulationData></xpdl:ExtendedAttribute>

Sequence Flow Parameters (TransitionSimulationData)This allows you to specify an expression that is evaluated to determine whether a Sequence Flow is traversed. In TIBCO Business Studio, this is specified as a Rule:

In this case, the sequence flow highlighted will only be traversed if the parameter isPaperworkCorrect is equal to Wrong receipts. This is specified as follows:


NumberOfCases <simulation:StartSimulationData NumberOfCases="100">

Specifies the number of Cases for simulation.

Duration <simulation:Duration><simulation:BasicDistribution><simulation:NormalRealDistribution Mean="5.0" StandardDeviation="2.0"/></simulation:BasicDistribution></simulation:Duration>

Specifies the distribution for case starts as one of the following:

• ConstantRealDistribution (Specify a decimal value for ConstantValue).

• UniformRealDistribution (Specify decimal values for LowerBorder and UpperBorder).

• NormalRealDistribution (Specify a decimal value for the Mean and StandardDeviation).

• ExponentialRealDistribution (Specify a decimal value for the Mean).



<xpdl:ExtendedAttributeName="TransitionSimulationData"><simulation:TransitionSimulationData>

<simulation:ParameterDeterminedCondition>true</simulation:ParameterDeterminedCondition><simulation:StructuredCondition>

<simulation:ParameterId>isPaperworkCorrect</simulation:ParameterId><simulation:Operator>=</simulation:Operator><simulation:ParameterValue>Wrong receipts</simulation:ParameterValue>

</simulation:StructuredCondition></simulation:TransitionSimulationData></xpdl:ExtendedAttribute>

This specifies that the Sequence Flow will only be traversed when the parameter isPaperworkCorrect has the value Wrong receipts.


ParameterDeterminedCondition

<simulation:ParameterDeterminedCondition>true</simulation:ParameterDeterminedCondition>

Specifies whether a parameter will be evaluated to determine flow through the Sequence Flow.

StructuredCondition <simulation:StructuredCondition><simulation:ParameterId>isPaperworkCorrect</simulation:ParameterId><simulation:Operator>=</simulation:Operator><simulation:ParameterValue>Wrong receipts</simulation:ParameterValue>

</simulation:StructuredCondition>

Specifies the condition that is evaluated to allow the Sequence Flow to be traversed. The condition is made up of:

• ParameterId

• Operator (>, =, >=, <, < =)

• ParameterValue



Parameter Distribution (WorkflowProcessSimulationData)Allows you to define simulation parameters and distributions. Simulation parameters are used in splits and in parameter-based distributions for Activities.

<xpdl:ExtendedAttributeName="WorkflowProcessSimulationData"><simulation:WorkflowProcessSimulationData>

<simulation:ParameterDistributionParameterId="ExistingCustomer">

<simulation:EnumerationValue Value="Yes" WeightingFactor="10.0"/><simulation:EnumerationValue Value="No" WeightingFactor="10.0"/>

</simulation:ParameterDistribution></simulation:WorkflowProcessSimulationData></xpdl:ExtendedAttribute>


ParameterDistributionId <simulation:ParameterDistributionParameterId="ExistingCustomer">

Specifies the parameter that will be evaluated to determine flow through the split.

EnumerationValue <simulation:EnumerationValue Value="Yes" WeightingFactor="10.0"/>

Specifies the possible values for the parameter.

WeightingFactor See EnumerationValue example. Specifies the weighting given to each transition in the split. For example, if each transition has the same weighting (10 in the previous example), the split will be 50:50.


| 31

Chapter 3 Writing an Import/Export Wizard

This chapter describes how to create either an import wizard for a file format that you want to import into TIBCO Business Studio or an export wizard for exporting a TIBCO Business Studio package into another file format.

Topics

• Overview, page 32

• Creating a New Import/Export Wizard Plug-in, page 33


32 | Chapter 3 Writing an Import/Export Wizard

Overview

Once you have written the XSLT that will be used either to import your files into TIBCO Business Studio or to export from TIBCO Business Studio into another format, you need to create a wizard that will allow users to perform the export or import. The New Import Wizard Plug-in and New Export Wizard Plug-in dialogs allow you to do this. Using these, you can create a plug-in for your product with all the required JAR files for exporting from and importing to TIBCO Business Studio.

This chapter describes import and export wizards for mappings implemented in XSLT. You can however use the Eclipse extension points and implement mappings in Java although this is beyond the scope of this document.


Creating a New Import/Export Wizard Plug-in | 33

Creating a New Import/Export Wizard Plug-in

To create a new export or import wizard plug-in, do the following.

1. Select New > Other. In the Select a wizard dialog, expand Other and select New Import/Export Plug-in Generator Wizard.

2. Click Next. The Plug-in Information dialog is displayed.

3. Enter the following information:

— Plug-in ID - ID which uniquely identifies your plug-in.

— Plug-in Version - Version information for your plug-in. This becomes part of the name of the JAR file when your plug-in is created.

When creating new plug-ins (for example, if you revised the XSLT), you should increment the version number to ensure the latest version is loaded by Eclipse.

Eclipse version numbers are specified in the form x.y.z.identifier where x, y and z are integers and identifier is a string (for example, I20060831).

— Plug-in Provider - Provider information for your plug-in.

— Plug-in Name - this is created from the ID that you enter with the Name appended. The default name is Plug-in, which is used if you select the Use default plug-in name check box. For example, if you enter an ID of MyImport, the name becomes MyImport Plug-in by default.

— Wizard Type - Select either Import or Export as appropriate.

Click Next. The Import Wizard Information or Export Wizard Information dialog is displayed, depending on the type of wizard you are creating.



4. Enter the following information:

— Wizard Title - This is the title that you want displayed in your Import/Export wizard and in the Import or Export listing.

— Wizard Description - Text description of what your wizard does.

— Output File Extension - this is used in the wizard to only display files whose extension match the filter. For example, if you specify .doc, only files with this extension are available for import/export.

— XSLT - Browse to specify the location of the XSLT that will be used for export/import.

— Schema (XSD or DTD) (optional) - Browse to locate the schema for the product you are importing. You can select either .dtd or .xsd files. Any schemas that you specify are validated.

— Category (optional) - Select the Category under which your wizard will be listed in the Import or Export listing (for example, Team, General, or Business Process Management).

— Icon - (optional) Browse to select an icon that will be displayed in the export/import listing.

Click Next. The Import/Export Wizard File Selection Filter dialog is displayed.

5. Depending on whether you are creating an import or export wizard:

— Select the special folders which can contain the imported resources.

— Select the special folders from which the resources to be exported can be selected.

You can also specify file extensions to limit the formats that can be exported or imported. When specifying more than one, use a comma-separated list (for example, XPDL, XML).

Click Next. The Plug-in Destination dialog is displayed.

6. Select how you want the Plug-in created:

— Install Plug-in - the Plug-in JAR files are created and installed as a plug-in in your Eclipse environment using the Plug-in information that you specified previously.

If you choose the Install Plug-in option, you are prompted to re-start Eclipse, which you must do to use your newly-created export import wizard.


Creating a New Import/Export Wizard Plug-in | 35

— Folder - Use this option if you want to distribute the plug-in to other users. The Plug-in is installed into the folder that you specify under the plugins/features sub-directory. If the plugins/features directory does not exist, it gets created automatically.

Click Finish.

7. Re-start Eclipse (if prompted) and ensure your wizard is displayed in the list (choose either File > Import or File > Export as appropriate).




| 37

Chapter 4 Deployment Framework

This chapter describes how to deploy your own artifact (Module) on a local or remote server.

Topics

• Overview, page 38

• Implementing Deployment, page 39

• Tutorial - Deployment to a WebDAV Server, page 45


38 | Chapter 4 Deployment Framework

Overview

The deployment framework allows you to deploy a resource (represented in TIBCO Business Studio as a Module) on a local or remote system (represented in TIBCO Business Studio as a Server). The Module can be a resource or set of resources, but it must be located using a Uniform Resource Locator (URL).

The deployment framework assumes that the physical machine referred to by the Server is running; you cannot start and stop the Server from within TIBCO Business Studio. However, you can connect and disconnect from the Server. Once connected, you can manage Modules and other objects on the Server by interrogating their states and performing operations on them.

The typical way deployment is used is as follows:

1. The user creates a Server within TIBCO Business Studio that contains all the necessary connection parameters and details.

2. The user connects to the running Server, deploys Modules, interrogates server objects and performs operations on them.

3. The user disconnects from the Server.

Deployment Repository

The deployment framework also supports the concept of a deployment repository. Modules that are going to be deployed are placed in the repository where the Server can obtain instances of the Modules to deploy. Using the repository allows the separation of deployment into two distinct phases:

• Providing the Module to the Server (for example, by sending them to a location known to the server).

• Actual deployment

Deployment repositories only handle the first phase of deployment (providing the Module).

Deployment Policy

The deployment framework also handles the deployment policy. Modules are stored in the Eclipse workspace, which means that they can have the following deployment policies:

• Deploy on request - the Module is only deployed (or redeployed) when the user explicitly chooses to do so.


Implementing Deployment | 39

• Deploy on save - the Module is deployed (or redeployed) whenever the Package is saved.

Implementing Deployment

This section describes the steps that you must follow to implement deployment.

The deployment framework provides the following:

• definition of the server type

• abstract connection

• server element structure.

TIBCO Business Studio provides extension points (some of which are optional) that you can implement to do the following:

• define the server

• specify the method of connection to the server

• define how the server elements will be retrieved from servers

• detail the operations and states that are possible from each operation.

Define the ModuleThe artifacts that you want to deploy are managed as Modules in TIBCO Business Studio. You also need to define how the Modules are created.

Define the Management OperationsWhen a Module is deployed on the server, you can use the TIBCO Business Studio user interface to perform operations on the deployed Modules. You must define these operations.



Defining the ServerThe com.tibco.xpd.deploy.core.ServerType extension point allows you to define the type of server on which you want to deploy. In your extension, you must provide a reference to a class that implements com.tibco.xpd.deploy.model.extension.ConnectionFactory, and optionally all necessary server configuration parameters. ConnectionFactory has one method, createConnection, that takes a Server object and should returns a connection specific to your server.

The connection to the server is represented by a class that implements the com.tibco.xpd.deploy.model.extension.Connection interface. For example:

public interface Connection extends IAdaptable {void connect();void disconnect();boolean isConnected();void refreshServerContent();Object deployModule(String url);Object performServerElementOperation(ServerElement

serverElement,Operation operation);

Server getServer();}

Connecting to a Server

Connection holds a reference to a server which you can obtain using the getServer() method. The Connect method is responsible for connecting to a Server. All necessary parameters needed to obtain connection can usually be taken from the server configuration, which is initialized when the server is created. The available configuration parameters are defined in the serverTypes extension point. The values for these parameters are provided by the user when creating an instance of the Server using the New Server Wizard.

When the connection with the server is established and valid, the isConnected() method should return true; otherwise it returns false.

When the connection is no longer needed, you can close the connection by invoking the disconnect() method.

Defining a Runtime (Optional)

A Runtime is configuration data that is shared amongst many server types. For example, if you use a client-side management system such as a JMX console to manage many servers, this server type could use common configuration details. This is implemented using the extension point com.tibco.xpd.deploy.core.runtimeTypes and by providing values for the necessary runtime parameters.



If a server type has an associated runtime, it should be reflected in the serverTypes extension by providing the associated RuntimeType sub element with the identifier of the runtime type extension.

Define the Possible Server ElementsNext, you must define the possible server elements and the method for obtaining them. You must do the following:

• define the hierarchy and way of displaying the elements in the Project Explorer

• you must create the structure such that it conforms to the Composite Design Pattern.

When the Framework needs to refresh, the method refreshServerContent retrieves the structure of objects on the server from which it builds the tree of server elements from the model.

Define States for ElementsYou must define the possible states in which an element can be. For example, an iProcess procedure can be Released, Unreleased, Withdrawn, and so on.

In this process you define the possible states for a given element type. For each operation, you also define the setTo state (the state that logically follows the success of the operation). The method getPossibleOperations defines the legal progression of states. For more information see Implementing Operations for ServerElements on page 57.

The operation names and states that you choose will be displayed in the user interface.



Configuring the RepositoryThe Repository is where a server can obtain Modules which are going to be deployed.The following diagram shows the phases of deployment based on the Java Business Integration (JBI) example:

• Phase 1 - The Module is published to the Repository and the inquiry URL is evaluated. The inquiry URL is an absolute or a relative URL of the Module in the Repository which is known and accessible from the server.

• Phase 2a, 2b -The deploy module operation is invoked on the server. The parameter of the deployment operation is the inquiry URL of the Module. The deployModule(String inquiryUrl) method which is a part of the Connection interface is responsible for this step.

Repository Types

Each server type must be associated with at least one repository type. There are two pre-defined repository types:

• Workspace - In this case, the publish action (Phase 1) does nothing, and the inquiry URL is the same as the URL of the Module in the workspace. This repository type is default, and it works well if the server is on the same machine as the client and the server can deploy Modules directly from the Eclipse workspace.

• Local folder - The repository will be located in a local folder or equivalent (for example mapped network folder, or WebDAV mapped folder). This repository type requires two additional configuration parameters:

— Publishing folder - a path to the repository folder.

— Inquiry URL prefix - a prefix of the enquiry URL that can be resolved on the server (the URL server will use this to obtain the module).



If you need to define another type of repository, implement the com.tibco.xpd.deploy.core.repositoryTypes extension point and reference the repository from the serverType extension. You also must provide the implementation of the com.tibco.xpd.deploy.model.extension.RepositoryPublisher interface for the newly defined repository type and provide any additional configuration parameters that are needed:

public interface RepositoryPublisher {public void publish(RepositoryConfig config, File file);public URL getInquiryUrl(RepositoryConfig config, File file);

}

The publish(RepositoryConfig config, File file) method is responsible for publishing Modules to the repository and will be invoked before deployment. The config parameter references all repository configuration parameters and their values (that were provided when the server was created). The second method: getInquiryUrl(RepositoryConfig config, File file) is for obtaining the inquiry URL corresponding to the file parameter.

If the repository type needs parameters, the values for which should be provided by the user, you should implement a repository configuration wizard page. To do this, extend the com.tibco.xpd.deploy.ui.repositoryConfigWizardPage extension. This extension requires the implementation of the com.tibco.xpd.deploy.ui.wizards.repository.RepositoryConfigWizardPage interface that defines the additional wizard page with configuration details:

public interface RepositoryConfigWizardPage extends IWizardPage {void init(RepositoryType type, RepositoryConfig config);void transferStateToConfig();

}

The init(RepositoryType type, RepositoryConfig config) method will be invoked before the page is created. This provides the RepositoryConfig reference that can be interrogated for configuration parameters and filled by the user accordingly. The configuration state can also be cached in controls and transferred to the configuration object just before finish. In this case, the appropriate code to transfer the state to the configuration has to be put to the transferStateToConfig() method.

Define the Deployment WizardYou need to define a wizard that allows users to deploy your Module. The key to this is that your artifact must be capable of being represented as a URL. Your deployment wizard must conform to the Eclipse iDeployWizard. This requires the implementation of getModulesURL.

In ui.deployWizards, you make the association between the server type id and the wizard.



When you deploy on the server, the extension point registry is searched, and the available wizards for the server type that you are deploying are displayed. The user then chooses a wizard.


Tutorial - Deployment to a WebDAV Server | 45

Tutorial - Deployment to a WebDAV Server

This tutorial shows how to use the TIBCO Business Studio Deployment Framework to create a plug-in for the deployment of a workspace file to a WebDAV (Web-based Distributed Authoring and Versioning) server. It also describes how to retrieve server objects, information about them, and how to implement operations performed on these objects.

WebDAV is an extension of the HTTP protocol designed to facilitate editing of web resources. In this tutorial, we will create a deployment system based on a WebDAV folder (also called a collection in WebDAV terminology). The TIBCO Business Studio Deployment module will be any workspace file. During deployment, the file will be put to the selected WebDAV folder which in our example we will call “site”. We will also display content of the site underneath the server and implement a delete operation which you can use to remove deployed files.

PrerequisitesThis section lists the tasks that you must complete before you can follow the tutorial.

Creating the Server

Create or obtain access to a WebDAV compatible server. Open source alternatives such as Apache Web Server WebDAV module are available as well as WebDAV support in commercial web server products. This tutorial uses Apache Slide, which is based on the Tomcat application server.

Apache Slide Installation

To install Apache Slide do the following:

1. Download the binary Tomcat bundle from:

http://jakarta.apache.org/slide/download.html

2. Unpack the zipped package.

3. Set the JAVA_HOME environment variable to root directory of Java SDK and run startup.bat (startup.sh on Unix systems). For detailed installation instructions, see http://jakarta.apache.org/slide/installation.html.

By default the server runs on port 8080, the default path to the WebDAV root is /slide, and the username and password are “root”.


http://jakarta.apache.org/slide/download.html

http://jakarta.apache.org/slide/installation.html


To test if the installation was successful, enter http://localhost:8080/slide in your browser. After providing the correct username and password, a simple directory structure should be displayed.

WebDAV client library

To communicate with the server, obtain a Java WebDAV client library. You can use the client provided as a part of Apache Slide project, but for the purposes of this tutorial, use the WebDAV support provided by Eclipse.

Eclipse WebDAV Support Installation

To install “DAV and FTP support plug-ins”, do the following:

1. Download eclipse-FTP-WebDAV-3.2.2.zip from:

http://download.eclipse.org/eclipse/downloads/drops/R-3.2.2-200702121330/

2. Unpack the content of the Eclipse subdirectory into the target platform or into the Eclipse/TIBCO Business Studio root directory.

After successful installation, the WebDAV support plug-ins should be listed as an installed plug-in.

Creating a WebDAV Server Type Extension1. To add a new server type (also called Runtime in TIBCO Business Studio) you

must extend com.tibco.xpd.deploy.core.serverTypes. By convention, servers are defined in separate eclipse plug-ins named com.tibco.xpd.deploy.server.servername. Therefore, create a new plug-in for the deployment server called com.tibco.xpd.deploy.server.webdav.

2. Next, provide the necessary dependencies:





3. Add the serverType extension that looks similar to the following:

<serverType connectionFactory="com.tibco.xpd.deploy.server.webdav.WebDavConnectionFactory" id="com.tibco.xpd.deploy.server.webdav" name="Web DAV"> <supportedRepository repositoryId="com.tibco.xpd.deploy.ui.WorkspaceRpository"> </supportedRepository> <configParameter key="siteUrl" label="&Site URL:" name="Site URL" parameterType="string" required="true"> </configParameter> <configParameter key="username" label="&User Name:" name="User Name" parameterType="string" required="false"> </configParameter> <configParameter key="password" label="&Password:" name="Password" parameterType="password" required="false"> </configParameter> <configParameter defaultValue="false" key="showSubfolders" label="Sho&w Sub Folders" name="Show Sub Folders" parameterType="boolean" required="true"> </configParameter></serverType>

— The connectionFactory attribute points to an instance of ConnectionFactory interface, and its purpose is to provide the server connection implementation class for a particular server:

public class WebDavConnectionFactory implements ConnectionFactory { public Connection createConnection(Server server) { return new WebDavConnection(server); }}



Connection implementation is the central class of the server and is described in Creating the Server Type Connection Implementation on page 48.

— Server type must support at least one repository type. There are two repository types already defined in the com.tibco.deploy.ui plug-in, but you can also define your own repository type by extending the com.tibco.xpd.deploy.core.repositoryTypes extension. This tutorial uses the default, com.tibco.xpd.deploy.ui.WorkspaceRpository, which simply provides deployment modules directly from Eclipse workspace.

— Finally, all necessary server connection parameters are defined:

siteUrl – URL to the WebDAV directory (also called collection) where files will be deployed.

username, password – Authentication information for the WebDAV server.

showSubfolders – Sets whether subfolders of the site should be shown. By default this parameter is false. If the repository is large, setting this parameter to true can cause refresh problems.

Creating the Server Type Connection ImplementationThe server type Connection implementation class is responsible for communication with a remote server including:

• connecting to / disconnecting from server

• deploying modules

• providing and refreshing server elements

• updating server state

• performing server element operations

The simplest form of Connection implementation could look like this:

public class WebDavConnection implements Connection { private final Server server;

public WebDavConnection(Server server) { this.server = server; } public void connect() throws ConnectionException { server.setServerState(ServerState.CONNECTED_LITERAL); }

public void disconnect() throws ConnectionException { server.setServerState(ServerState.DISCONNECTED_LITERAL); }



public boolean isConnected() throws ConnectionException { return server.getServerState() == ServerState.CONNECTED_LITERAL; }

public DeploymentStatus deployModule(String url) throws DeploymentException {return new DeploymentSimpleStatus( DeploymentSimpleStatus.Severity.OK, "", null); }

public void refreshServerContent() throws ConnectionException { }

public Server getServer() { return server; }

public Object performServerElementOperation(ServerElement serverElement, Operation operation) throws DeploymentException { return null; }

public Object getAdapter(Class adapter) { return null; }}

Although this implementation only changes the server state on a connect or disconnect action, it is sufficient for the purposes of the tutorial.



In TIBCO Business Studio, you should now be able to start the New Server Wizard and choose Web DAV as the Runtime. For example:



If you select Web DAV as the runtime, on the screen that follows, you can view the rendered parameters of the server and the assigned repository. The widgets to capture parameter values are automatically generated using the parameter descriptions provided in the extension.

After clicking the Finish button, you can view the new server created under the Deployment Servers in the Project Explorer. You can also invoke connect and disconnect actions from the context menu and as a result see the server state change.

Connecting to WebDAV serverTo make a real connection to the server, you must implement the connect() method. The following example implementation of the method checks if the authentication information is correct for the provided site, and also checks that the site is a valid WebDAV resource.

private CollectionHandle siteHandle;

public void connect() throws ConnectionException { ServerConfig config = server.getServerConfig(); String siteUrl = config.getConfigParameter(“siteUrl”). getValue().toString(); String username = config.getConfigParameter(“username”). getValue().toString(); String password = config.getConfigParameter(“password”). getValue().toString();



try { password = EncryptionUtil.decrypt(password); } catch (IllegalArgumentException e) { throw new ConnectionException( "Connection failed. " + "Password has changed in the servers configuration file. " + "Please re-enter the server password.", e); } WebDAVFactory davFactory = new WebDAVFactory(); HttpClient httpClient = new HttpClient(); httpClient.setAuthenticator(new SimpleBasicAuthenticator(username, password)); DAVClient davClient = new RemoteDAVClient(davFactory, httpClient); ILocator siteLocator = davFactory.newLocator(siteUrl); siteHandle = new CollectionHandle(davClient, siteLocator); try { if (siteHandle.canTalkDAV()) { server.setServerState(ServerState.CONNECTED_LITERAL); } else { throw new ConnectionException( "Cannot connect to WebDAV site."); } } catch (DAVException e) { throw new ConnectionException(e); }}

In this example, the server parameters’ values are read from the server configuration. Then, we create davClient and siteLocator (which is responsible for locating DAV resource). Next we create CollectionHandle (the proxy for a remote resource) for the site and invoke the canTalkDAV() method. This method checks if the connection to the server can be made, and if the corresponding remote resource is a valid WebDAV collection resource.

The WebDAV is a request response protocol, so there is no explicit session associated with a connection. However, the HttpClient used by siteHandle does contain some session information (for example authentication information) that is sent with every request.



Providing Server ElementsThe server can contain multiple ServerElement objects which represent objects on the server (usually existing modules). They are displayed in the Project Explorer under the server and can be arranged in a hierarchical structure:

The refreshServerContent() method from the Connection interface is responsible for providing and updating server elements. The following example shows an implementation of the method for a WebDAV server.

public void refreshServerContent() throws ConnectionException { if (isConnected() && siteHandle != null) { try { refreshServer(siteHandle); } catch (DAVException e) { server.getServerElements().clear(); disconnect(); throw new ConnectionException(e); } } else {



server.getServerElements().clear(); }}

private void refreshServer(CollectionHandle site) throws DAVException { boolean showSubfolders = Boolean.parseBoolean(WebDavConstants .getConfigParamValue(server.getServerConfig(), WebDavConstants.SHOW_SUBFOLDERS)); HashSet<String> existingFileNames = new HashSet<String>(); HashSet<String> existingDirNames = new HashSet<String>(); Set<AbstractResourceHandle> members = site.getMembers(); for (Iterator iter = server.getServerElements().iterator(); iter .hasNext();) { ServerElement se = (ServerElement) iter.next(); String name = se.getName(); if (se instanceof ModuleContainer) { boolean exist = false; for (AbstractResourceHandle member : members) { if (isCollectionMember(member) && name.equals(getMemberName(member))) { if (showSubfolders) { refreshCollection((CollectionHandle) member, (ContainerElement) se); } exist = true; existingDirNames.add(name); } } if (!exist) { iter.remove(); } } else if (se instanceof ServerModule) { boolean exist = false; for (AbstractResourceHandle member : members) { if (!isCollectionMember(member) && name.equals(getMemberName(member))) { setModuleProperties((ServerModule) se, member); exist = true; existingFileNames.add(name); } } if (!exist) { iter.remove(); } } } for (AbstractResourceHandle member : members) { String memberName = getMemberName(member); if (isCollectionMember(member)) { if (!existingDirNames.contains(memberName)) { ModuleContainer moduleContainer = DeployFactory.eINSTANCE .createModuleContainer(); moduleContainer.setName(memberName); if (showSubfolders) {



refreshCollection((CollectionHandle) member, moduleContainer); } server.getServerElements().add(moduleContainer); } } else { if (!existingFileNames.contains(memberName)) { ServerModule module = DeployFactory.eINSTANCE .createServerModule(); module.setName(memberName); setModuleProperties(module, member); server.getServerElements().add(module); } } }}

During the method invocation, we connect to the WebDAV server and obtain remote resources’ information. Then we create corresponding server modules and/or update their state and properties.

When the user disconnects from the server, all server elements should be removed.

In a future implementation, the server elements could be enhanced to better support hierarchical structures of server objects.

Deploying ModulesTo implement modules deployment we will have to do the following:

• Implement DeploymentStatus deployModule(String url) method for the Connection implementation.

• Provide a deployment wizard.

Implementing the deployModule Method

The following example shows an implementation of the deployModule method for a WebDAV server. This method is responsible for the deployment of a single file to the WebDAV site.

public DeploymentStatus deployModule(String url) throws DeploymentException { Assert.isNotNull(siteHandle); Assert.isTrue(url != null && url.trim().length() > 0); InputStream inputStream = null; String deploymentMsg = "Deploying: " + url; try { DAVClient client = siteHandle.getDAVClient(); String remoteUrl = getSiteRelativeURL(siteHandle, url); ILocator resourceLocator = client.getDAVFactory().newLocator(



remoteUrl); URL localUrl = new URL(url); inputStream = localUrl.openStream(); IResponse response = client.put(resourceLocator, client .getDAVFactory().newContext(), inputStream); int statusCode = response.getStatusCode(); String statusMessage = response.getStatusMessage(); String responseMessage = "\n" + statusCode + ':' + statusMessage; if (statusCode == IResponse.SC_CREATED || statusCode == IResponse.SC_NO_CONTENT) { return new DeploymentSimpleStatus( DeploymentSimpleStatus.Severity.OK, deploymentMsg + responseMessage, null); } else { return new DeploymentSimpleStatus( DeploymentSimpleStatus.Severity.ERROR, deploymentMsg + responseMessage, null); } } catch (IOException e) { return new DeploymentSimpleStatus( DeploymentSimpleStatus.Severity.ERROR, deploymentMsg, e); } finally { try { inputStream.close(); } catch (IOException e) { // TODO Log error e.printStackTrace(); } }}

The method’s parameter is a string that contains the URL of the file in the deployment repository (also called the inquiry URL). Because we use “Workspace Repository” this URL is the same as the URL of the local file. Before the module is deployed, it is published to the server repository and the repository is asked to provide the inquiry URL for the published module. This inquiry URL is passed as a parameter to the deployModule method, and it is used by the server to access the module from the repository (it could be different to the local module URL).

Providing the Deployment Wizard

This section describes how to provide a deployment wizard and associate it with the WebDAV server type by implementing the com.tibco.xpd.deploy.ui.deployWizards extension point.

<extension point="com.tibco.xpd.deploy.ui.deployWizards"> <deployWizard



class="com.tibco.xpd.deploy.server.webdav.ui.WorkspaceFileDeployWizard" id="com.tibco.xpd.deploy.server.webdav.workspaceFileWizard" name="Workspace File" serverTypeId="com.tibco.xpd.deploy.server.webdav"/></extension>

The main purpose of a deployment wizard is to provide a list of URLs for local modules. To do this, the wizard class must implement IDeployWizard. The most important method in this interface is List<URL> getModulesUrls(), which (after the wizard finishes) should return a list of modules’ local URLs.

Implementing Operations for ServerElementsTo implement operations for server elements, you must define the following:

• Types of elements

• Possible states for a defined element type

• Operations that can be performed

• Operations that can be performed when an element is in a particular state

It is also necessary to set the correct type and state for every server element created when calling the refreshServer method.

The following code fragment shows how to create and configure all necessary elements to implement a WebDAV module (file) delete operation.

private OperationImpl deleteFileOperation;private ServerElementType fileType;private ServerElementState publishedState;

private void initialiseServerElementTypes() { DeployFactory f = DeployFactory.eINSTANCE; fileType = f.createServerElementType();

// states. States should not be shared between different element types publishedState = f.createServerElementState(); publishedState.setName("Published");

// all states server element type could be in fileType.getStates().add(publishedState);

// operations deleteFileOperation = new OperationImpl() { @Override public Object execute(ServerElement serverElement) throws DeploymentException { try { return deleteRemoteFile(serverElement); } finally {



refreshServerContent(); } } }; deleteFileOperation.setName("Delete");

// all available operations for server element type fileType.getOperations().add(deleteFileOperation);

// possible operations for states publishedState.getPossibleOperations().add(deleteFileOperation);}

Also when you create modules using the refreshServer method, you must set an element’s type and state as follows:

serverElement.setServerElementType(fileType);serverElement.setServerElementState(publishedState);

SummaryThis tutorial showed how to use the TIBCO Business Studio Deployment Framework to create a plug-in for the deployment of a workspace file to a WebDAV server. It also described how to retrieve server objects, information about them, and how to implement operations performed on these objects.

Other Framework Features

The following features are available, but were not demonstrated by this tutorial:

• The ability of the deployment framework to allow you to create additional module repository types.

• The reuse of configuration information in a client runtime. This is useful, for example, if many server types use common configuration data or a common platform on the client side. This common configuration information can be stored by the client runtime which can be shared by multiple servers. For more information about runtimes, see Defining a Runtime (Optional) on page 40.

• "On save" module deployment, in which a module is automatically deployed when the content of the module changes.


Documents

Business Studio Customization