# SOA Console User Guide

### Orchestra Team

Copyright © 2010 Bull SAS - OW2 Consortium

Abstract

This document contains an installation and user guide for SOA Console included in Orchestra 4.5.0

## Introduction

This documentation is targeted to Orchestra users. It presents the installation procedure and a quick user guide of the SOA Console features.

Chapter 1, Overview Gives an overview of the SOA Console

Chapter 2, Installation Describes how to install the SOA Console

Chapter 3, Quick Start Quick start information of the SOA Console

Chapter 4, User Guide Gives a complete description of the SOA Console.

## Chapter 1. Overview

## 1.1. SOA Console Overview

This document describes the SOA Console capabilities.

This console is used to administrate SOA platforms. This first version only communicates with Orchestra, Camel will follow soon.

This is a functional console which gives the possibility to administrate your SOA platform monitoring the different entities from processes to activities. The "User Guide" section explains in details each feature.

## Chapter 2. Installation

## 2.1. Prerequisite

To install the console or the engine, you'll need to have Apache Ant version 1.7 or later available on your computer. It can be downloaded it from Apache Ant website.

## 2.2. Installation procedure

Two versions of the SOA Console are available. You can either use the full version which contains both the Orchestra engine and the SOA Console, or you can use the SOA Console package which gives the possibility to connect to an existing Orchestra engine.

### 2.2.1. SOA Console with Orchestra engine

To use the SOA Console with Orchestra engine, get its latest version from Orchestra download page on OW2 forge : http://forge.ow2.org/projects/orchestra

Extract it and go in the orchestra-cxf-tomcat-X.X.X directory. Once you're in, just execute : ant start

### 2.2.2. SOA Console alone

This section is aimed at users who wants to use the SOA Console with an existing Orchestra engine.

To do this, you can download the SOA Console without Orchestra from Orchestra download page on OW2 forge : http://forge.ow2.org/projects/orchestra

Then, you need to extract the WAR in the webapps folder of a tomcat server.

Last step is to modify the JMX information of orchestra.properties (in WEB-INF/classes directory of the extracted war). You'll need to change the port, service url and object name with your Orchestra engine ones :

    					# Port of the JMX registry
    					orchestra.jmx.port=9999
    					# JMX Service URL to connect to orchestra mbean server.
    					orchestra.jmx.serviceUrl=service:jmx:rmi:///jndi/rmi://localhost:9999/orchestraServer
    					# Name of the Orchestra MBean
    					orchestra.jmx.objectName=Orchestra:type=RemoteAPI

## Chapter 3. Quick Start

In this chapter we present a quick start documentation for SOA Console. In the next chapters we will explain in more details the functionalities available in this release.

The first step to begin with SOA Console is to log on the server. To do this, you have to :

- Open a command line and execute the following under the orchestra-cxf-tomcat-X.X.X directorty :

ant start

- In your web browser connect to the following URL : http://localhost:8080/console/ It's the default url, otherwise the correct syntax is : http://hostname:portnumber/console

You'll have to connect with :

1. User Name : orchestra

2. Password : orchestra

## Chapter 4. User Guide

In this chapter we present the possibilities of the SOA Console.

## 4.1. Default Users

By default, the SOA Console has one user registered. It's important to change this users' list as soon as possible to control the access on your engine. To do this, you'll find a "tomcat-users.xml" file in repository tomcat/conf/ and you'll have to modify these following lines to modify the access list :

    					<tomcat-users>
    					<!--
    					  NOTE:  By default, no user is included in the "manager" role required
    					  to operate the "/manager" web application.  If you wish to use this app,
    					  you must define such a user - the username and password are arbitrary.
    					-->
    					<!--
    					  NOTE:  The sample user and role entries below are wrapped in a comment
    					  and thus are ignored when reading this file. Do not forget to remove
    					  <!.. ..> that surrounds them.
    					-->
    					<!--
    					  <role rolename="tomcat"/>
    					  <role rolename="role1"/>
    					  <user username="tomcat" password="tomcat" roles="tomcat"/>
    					  <user username="both" password="tomcat" roles="tomcat,role1"/>
    					  <user username="role1" password="tomcat" roles="role1"/>
    					-->
    					  <user username="orchestra" password="orchestra" roles="user"/>
    					</tomcat-users>

The roles are defined in web.xml file. By default, you can log with user and admin as role but this version doesn't implement the role mechanism.

This is the standard authentication mechanism for servlet container, you can find more details on this url : http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html

## 4.2. Process View

This is the first view you'll see when connecting to the console. Its purpose is to display the processes on Orchestra but you can switch to the instances tab to display the instances on Orchestra. This is the global mechanism to change view for the entire application.

You have the possibility on each view to sort the tables as you want clicking on the title labels except Actions one.

### 4.2.1. Deploy a process

In the processes view tab, you have the possibility to deploy a process :

Once you have clicked the browse button, you'll have to choose a process to deploy through your filesystem. On Orchestra, processes are .bar files containing at least one wsdl file and one bpel file.

Choose your process to deploy and click the upload button :

Once Orchestra has finished to deploy the process, the Processes tab will automatically refresh with the new process and a popup information will be displayed :

To test the console, you can use the Orchestra examples delivered within the package running the command : ant deploy. You can use the fileupload widget too but make sure that the port in soap:adress in the wsdl file is the same as the tomcat port.

You can also run instances with the command : ant launch

### 4.2.2. Information about a process

For each process deployed on Orchestra, the following fields will be displayed :

1. UUID

   It's the ID of the process on Orchestra. This ID is unique, it can correspond to only one process.

2. Name

   It's the name of the process deployed

3. Namespace

   It's the namespace of the process. The concatenation of name and namespace identifies a unique deployed process too.

4. Deployment Date

   It's the date when the process has been deployed on Orchestra.

5. Undeployment Date

   It's the date when a process has been undeployed. For a process not undeployed yet, this field will be "N/A" for Not Applicable.

6. State

   It's the state of the process, the different values are "deployed" or "undeployed"

7. Actions

   It's the different actions possible on each process.

### 4.2.3. Actions on a deployed process

In the last column of the grid, you'll find the actions possible on a process :

Icon Description :

1. a new tab is added with instances of the corresponding process.

2. a new tab is added with details and definition activities of the corresponding process.

3. the process will be undeployed. It will always be on the process list but its state will be undeployed and so, it will not be possible to instantiate it.

4. the process will be totally removed from engine, contrary to the undeployment.

Note that these icons are disabled when the actions are not possible.

## 4.3. Instance View

The second tab will always be a list of all instances of all processes on Orchestra but you can, with actions bar, open a new view with instances for a specific process.

### 4.3.1. Information about an instance

For each instance executed on Orchestra, the following fields will be displayed :

1. UUID

   It's the ID of the instance on Orchestra. This ID is unique, it can correspond to only one instance.

2. Process UUID

   It's the unique ID of the process corresponding to the instances displayed.

3. Process Name

   It's the name of the process corresponding to the instances displayed.

4. State

   It's the state of an instance. The different values are "running", "suspended", "finished" or "exited".

5. Start Date

   It's the date when the instance has begun.

6. Last Update Date

   It's the date of last update of the instance and the end date for an instance terminated.

7. Actions

   It's the different actions possible on each instance.

### 4.3.2. Actions on an instance

In the last column of the grid, you'll find the actions possible on an instance :

Icon Description :

1. a new tab is added with details and activities corresponding to the selected instance.

2. the instance will be suspended until you click on the next icon.

3. the instance previously suspended will be resumed.

4. the instance will be terminated and its state will be "exited".

5. the instance will be totally removed from the history base.

Note that these icons are disabled when the actions are not possible.

## 4.4. Activities View

This view is displayed on its own tab when you click on the activities icon as explained in the previous section. You can open an activities tab for a process, these activities will be the definition activities of the process. You can open an activities tab for an instance, these activities will be the runtime activities of the specific instance, so you'll see what activities are already done by the instance and which one is running. Definition activities and execution activities contain 2 separate views :

1. Details view : This first grid gives information about the process/instance.

2. Activity view : This second grid gives the whole list of activities executed by a process for a process and the list of activities already executed for an instance.

Note that in the details view, you have the possibility to interact with the process/instance selected thanks to the Actions column as explained in previous section.

## 4.5. Other Features

Some other features are available when any tab is selected. You can :

1. Sort your grids depending on every field except Actions.

2. Check your connection to Orchestra at any time on the info labels just below the banner. The refresh label allows you to check if the connection to Orchestra is always unavailable.

3. Check your login information on the same info banner.

4. Logout from the console at any time clicking the Logout label.