Orchestra User Guide

Orchestra Team

Goulven Le Jeune

Abstract

This document presents a guide to install & use Orchestra.


Table of Contents

Introduction
1. General information
1.1. Nova Orchestra Overview
1.2. Features list
1.3. Restrictions
1.4. Configuration environment
1.5. Tooling
2. Prerequisites
2.1. Hardware
2.2. Software
3. Installation guide
3.1. Installation
3.2. Orchestra directory structure
4. User guide
4.1. Start and Stop Nova Orchestra
4.2. Deploying / undeploying a process
4.3. Other commands
4.4. Running the examples
4.5. Running the tests
4.6. Configuring Logger

Introduction

This documentation is targetted to Orchestra users. It presents the installation procedure and the use of Nova Orchestra.

Chapter 1, General information describes the new version Orchestra v4 called Nova Orchestra

Chapter 2, Prerequisites describes the prerequisites to the installation of Nova Orchestra

Chapter 3, Installation guide describes how to install the Orchestra engine

Chapter 4, User Guide This chapter will guide you through the discovery of the functionalities of Nova Orchestra.

Chapter 1. General information

1.1. Nova Orchestra Overview

Nova Orchestra is the name of new version of Orchestra.

“Nova” technology is based on the “Process Virtual Machine” conceptual model for processes. The Process Virtual Machine defines a generic process engine enabling support for multiple process languages (such BPEL, XPDL…).

On top of that, it leads to a pluggable and embeddable design of process engines that gives modelling freedom to the business analyst. Additionally, it enables the developer to leverage process technology embedded in a Java application.

For more information about the Process Virtual Machine, check Nova Orchestra FAQs on the Orchestra web site.

1.2. Features list

Nova Orchestra is a Web Service Orchestration engine that provide BPEL 2.0 support. Business Process Execution Language (BPEL) is an XML language created by the Oasis Consortium. More information and the specifications can be found on Oasis web site

Nova Orchestra M1 provides partial BPEL 2.0 support. Hereafter, you can find the list of the activities supported in this milestone :

  • Scope

  • Receive

  • Reply

  • Invoke

  • Assign

  • Empty

  • Sequence

  • Flow

  • If

This milestone provides Web Service support using the Axis 1.4 framework.

Nova Orchestra is shipped with a complete test suite and a few examples.

1.3. Restrictions

This first milestone of Nova Orchestra is aimed at showing the power of its very innovative architecture by providing support for all the basic activities defined in the BPEL standard. Future milestones will continue to improve the standard coverage as well as other functionalities like persistence and other services. Check the roadmap for more information.

This first milestone does not support the following features :

  • No fault management

  • Correlation just for receive

  • No static analysis

  • Some restrictions in assign statement :

    • no extensionAssignOperation

    • to partnerlink not supported

    • validate not supported

  • Some restrictions in scope statement

    • isolated not supported

    • exitOnStandardFault not supported

    • partnerlink : dynamic update of endpoints

    • handlers not supported

  • The following BPEL 2.0 statements are not supported :

    • throw / rethrow

    • exit

    • wait

    • while

    • repeatUntil

    • forEach

    • pick

    • compensate

    • compensateScope

    • validate

    • extensionActivity

    • import

    • extensions

1.4. Configuration environment

The PVM includes a framework to allow the injection of services and objects that will be leveraged during the process definition and execution. Objects and services required in Orchestra are defined through an XML file. A dedicated parser and wiring framework in the PVM is in charge of creating those objects.

A default environment file (environment.xml) is provided in the installed package.

Currently, following objects are required for the execution environment :

  • servicePublisher

  • deployer

  • serviceInvoker

  • languageProcessor_XPath

  • queryExecutor_XPath

  • expressionExecutor_XPath

  • processRepository

  • DOMGetVariablePropertyFunction

Example of implementation classes for these objects are embedded into the Orchestra jar and defined into the environment.xml file.

1.5. Tooling

For the new version, Nova Orchestra does not ship a graphical designer. Nova Orchestra engine has been tested with processes created using the Eclipse BPEL designer. Download and installation instruction are available on the project web site.

The first milestone of Nova Orchestra does not yet provide an administration and monitoring console. However a brand new Web 2.0 console will be available very soon. Check the Nova Orchestra roadmap for details !

Chapter 2. Prerequisites

Table of Contents

2.1. Hardware
2.2. Software

2.1. Hardware

A 1GHz processor is recommended, with a minimum of 512 Mb of RAM. Windows users can avoid swap file adjustments and get improved performance by using 1Gb or more of RAM

2.2. Software

  • Nova Orchestra requires Java Development Kit (JDK) 1.5 (also called JDK 5.0) but also runs with with next release.

    The JDK software can be downloaded from http://java.sun.com/j2se/1.5.0

  • Nova Orchestra requires Apache Ant 1.6.5 or higher

    It can be downloaded from http://ant.apache.org

  • Nova Orchestra runs in Apache Tomcat servlet container. It has been tested with Tomcat 5.5.17 and Tomcat 5.5.25.

    Tomcat can be downloaded from http://tomcat.apache.org/

Chapter 3. Installation guide

3.1. Installation

Unzip the orchestra-axis distribution package.

>unzip orchestra-4.0.M1.zip

A new directory orchestra-4.0.M1 will be created. It contains an ant file to install and start Orchestra.

Warning : Tomcat should be installed and the environment variables CATALINA_HOME and CATALINA_BASE set before starting the installation procedure.

To install Orchestra, go to orchestra directory and launch the install by running ant:

>cd orchestra-4.0.M1
>ant install

The install script will ask some questions, and then install orchestra and launch Tomcat. After the installation and before starting Tomcat, do not forget to update Tomcat security policy :

To run, Orchestra webapp requires special security permissions. Please add these lines (change the values of axis.webappDir and axis.webappName according to your environnement. The exact lines to be inserted are given at the end of the installation process) to your catalina.policy file in ${env.CATALINA_BASE}/conf before starting tomcat :

grant codeBase "file:<axis.webappDir>/<axis.webappName>/WEB-INF/-" {
    permission java.security.AllPermission;
};

3.2. Orchestra directory structure

Hereafter is detailled the structure of Orchestra installation. The installation directory contains the following structure :

README
build.xml
install.xml
licence.txt
conf/
doc/
examples/
lib/
Let's present those items :

  • README

    This file gives the basic information related to Nova Orchestra

  • build.xml

    This file is an ant file that provides tasks to install and use Nova Orchestra. Just typing ant will result giving you the usage.

  • install.xml

    This file is an ant file that is called when you run ant install (no need to specify the use of this file)

  • license.txt

    The license of Nova Orchestra. All of Nova Orchestra is available under the LGPL license.

  • conf/

    This directory contains all the configuration files of Nova Orchestra

  • doc/

    This directory contains the documentation of Nova Orchestra. It contains 2 directories :

    • html/

      For HTML documentation

    • pdf/

      For PDF documentation

    • html-single

      For HTML documentation in a single page

  • examples/

    This directory contains some examples provided with Nova Orchestra package. The 2 examples provided are :

    • loanApproval

      This is an example from the BPEL 2.0 standards

    • weather

      This example shows how to call a real world Web Service.

  • lib/

    This directory contains the libraries used in Nova Orchestra.

Chapter 4. User guide

4.1. Start and Stop Nova Orchestra

Nova Orchestra M1 is a webapp that can be deployed on Tomcat. So starting Nova Orchestra in fact starts Tomcat with the correct environment. This can be performed from the intallation directory with the following command line :

>cd orchestra-4.0.M1
>ant start

Starting Orchestra will not be done in background. This means that the console starting Orchestra will be dedicated to the traces from Orchestra. To perform further actions, new consoles need to be opened.

To stop Nova Orchestra, type the following command line :

>cd orchestra-4.0.M1
>ant stop

4.2. Deploying / undeploying a process

Once Nova Orchestra is started, it is then possible to deploy a new process on the engine :

>ant deploy -Dbpel=<process>.bpel -Dwsdl=<process>.wsdl -Dextwsdl=<wsdl1,wsdl2>

Nova Orchestra also provides the possibility to use an archive to deploy a process. This archive should be a zip file with the extension .bar. Here is the command line to deploy such an archive :

>ant deploy -Dbar=<process>.bar

Warning : The archive should be a zip file structured as described bellow :

/bar.properties
/<process>.bpel
/<process>.wsdl
/<files>.wsdl

The bar.properties file should have the following structure :

bpel=<process>.bpel
wsdl=<process>.wsdl
extwsdl=<file1>.wsdl,<file2>.wsdl,...

To undeploy a process, use the following command line :

>ant undeploy -Dprocess=<process_name>

Warning : the process name should be fully qualified. This means that it needs to contain to namespace. For instance :

{http://orchestra.ow2.org/weather}weather

4.3. Other commands

Nova Orchestra provides a set of other commands that can be usefull

  • A command to check the status of Nova Orchestra. This command tells if the engine is started and if so, gives the names of processes deployed on the engine :

    >ant status
    
  • A command to simulate a Web Service call. This command will simulate a WS call to interact with a deployed process :

    >ant call -Dendpoint=<service_url> -Daction=<SOAP_action> -Dmessage=<message>
    

    For example :

    >ant call -Dendpoint=http://localhost:8080/orchestra/services
              -Daction=http://orchestra.ow2.org/weatherArtifacts/process/weatherPT
              -Dmessage="<weatherRequest xmlns='http://orchestra.ow2.org/weather'>
                        <input>Grenoble,France</input>
                        </weatherRequest>"
    

4.4. Running the examples

The Nova Orchestra package contains two examples of BPEL processes:

  • loanApproval : invokes two local web services. This example is taken from the BPEL 2.0 standard.

  • weather: invokes a remote Web Service and returns the current weather.

A build.xml file is provided for each of those samples. Those ant scripts provide the same targets to deploy, launch and undeploy the sample. Go to the desired example and use the command lines :

>ant deploy
>ant launch
>ant undeploy

4.5. Running the tests

Nova Orchestra is delivered with a test suite to check if your installation is correct. There are 3 differents tests available :

  • Core test suite. This suite tests the core functionnalities of the engine (e.g. BPEL activities, variables, etc...). This test suite can be launched with the following command :

    >ant test
    
  • Axis test suite. This suite gives the possibility to test the Axis Web Service stack deploying and launching real processes. This test suite can be launched with the following command :

    >ant test-axis
    
  • Stress test suite. This suite will launch a small stress test. This test suite can be launched with the following command line :

    >ant test-stress
    

A command is also provided to launch those 3 test suites at once :

>ant test-all

The results of the tests are available under the directory test/results.

4.6. Configuring Logger

It is possible to activate the logs. To do so, the file logging.properties under the directory $CATALINA_BASE/webapps/orchestra/WEB-INF/classes can be edited. Here is the content of that file :

handlers= java.util.logging.ConsoleHandler
.level= SEVERE
java.util.logging.ConsoleHandler.level = FINEST
java.util.logging.ConsoleHandler.formatter = org.jbpm.util.JbpmFormatter

# For example, set the com.xyz.foo logger to only log SEVERE messages:
# com.xyz.foo.level = SEVERE

#org.jbpm.pvm.level=INFO
#org.ow2.orchestra.level=FINEST
#org.jbpm.pvm.Execution.level=FINEST
#org.jbpm.wire.level=FINEST

Uncomment the last lines to activate the logs.