BSOA Orchestra Administrator's Guide

Table of Contents

 

Chapter 1.             The Purpose of This Guide 1

Chapter 2.             Administration Console Description 3

2.1   Console Loading. 3

2.2   Console Frames Description. 4

Chapter 3.             User Management 7

3.1   Orchestra User Management Basic Configuration. 7

3.2   Orchestra Profiles 8

3.3   How To Change the Basic Configuration. 9

3.4   How To Initiate a New Datasource Security Realm for Use by Orchestra. 11

3.4.1      Create the Database. 11

3.4.2      Initialize the Database(s) 12

3.5   How To Configure an Ldap Directory For Use By Orchestra – LoginModule Feature. 12

3.6   How To Select a New Security Realm For User Management 16

3.7   How To Access the Description Of a Specific Realm.. 18

3.8   How To Access the Users List for a Specific Realm.. 19

3.9   How To Add a User To a Specific Realm.. 20

3.10 How To Suppress a User From a Specific Realm.. 21

3.11 How To Access the List of Users Involved In a specific BSOA Profile. 22

3.12 How To Modify the BSOA Profile or Password For a Specific User 23

Chapter 4.             Engine Databases 25

4.1   How To Change Basic Engine Datasource. 25

4.2   How To Look at the Engine Datasource Definition. 26

Chapter 5.             Editing Custom Properties 27

Chapter 6.             Setup. 29

 

List of Figures

 

Figure 2‑1.    Logon Screen for the Process Administration Console. 3

Figure 2‑2.    Administration Console Frames 4

Figure 3‑1.    Orchestra User Management Basic Configuration. 7

Figure 3‑2.    Illustration of Scope of the Orchestra Profile Roles 8

Figure 3‑3.    Changing the Basic Configuration for User Management 9

Figure 3‑4.    User Management Core Frame of Administration Console. 16

Figure 3‑5.    Confirmation Warning When Selecting a New Realm.. 17

Figure 3‑6.    User Management Core Frame Displaying Selected and Available Realms 18

Figure 3‑7.    Display of Information for a Selected Realm.. 18

Figure 3‑8.    User Management Core Frame Displaying Selected Realm.. 19

Figure 3‑9.    List of Users for a Selected Realm.. 19

Figure 3‑10.  New User Registration Form.. 20

Figure 3‑11.  Remove Users Form.. 21

Figure 3‑12.  List of Profiles for a Selected Realm.. 22

Figure 3‑13.  List of Users in a Specific BSOA Profile. 22

Figure 3‑14.  User Information Form.. 23

Figure 4‑1.    Bpel Datasource Configuration Display. 26

Figure 5‑1.    Custom Properties Configuration form.. 27

Figure 6‑1.    Setup Panel 29

 


Preface

 

This guide describes which facilities the Process Console provides to users via the Administrator function.

For an explanation about the different BSOA roles and how to modify these profiles, see the “How To Modify the BSOA Profile or Password For a Specific User” section in this document.


Chapter 1.      The Purpose of This Guide

This guide provides the information necessary to:

·           Modify the basic configuration for user management (Ldap or Datasource Realm),

·           In case of Datasource Realm, Add or Remove user, Specifying BSOA profiles for BSOA users,

·           Access Orchestra engine Datasource configuration: JNDI name, port number, etc.

 

 

 


Chapter 2.      Administration Console Description

2.1                       Console Loading

To access the Process Administration Console, connect to the following URL http://Your_Host:Your_HttpPort/jiapAdmin
(default: http://localhost:9000/jiapAdmin/).

 

Figure 21.    Logon Screen for the Process Administration Console

 

After the installation step is completed, the default user for Process Console Administrator is bsoa (bsoa).

 


2.2                       Console Frames Description

After logging in, the Administration Console is available in the main frame of a browser. It is divided into four parts (five if the footer frame is configured), each with a specific profile.

 

Figure 22.    Administration Console Frames

 

 

Navigational Tree

Use this frame to navigate between the different options the console offers, which are based on the user profile and the user-application context.

Click either on the  /  signs, or on the desired labels to expand/retract a branch.

For a terminal node, the Core Frame then presents the corresponding information.

Header Frame

By default, this frame displays the title and icon of the Process Console. The console administrator may customize the content of this frame by displaying the content of a configured URL. (See Customizing Header/Footer URLs below.)

Utility Frame

This frame displays the name of the user who is logged in, a  button to refresh the header, core and footer frames, and a  button to exit the console. It also displays the path corresponding to the actual information shown in the Core Frame.


Core Frame

This is the main frame of the console. A navigational path showing the tree structure of the information displayed, along with the actual information, is available. Different tabs may be accessed in this zone and all information entered will be displayed within it.

Footer Frame

By default this frame is not displayed. The console administrator may configure this frame to display the content of a configured URL (see Customizing Header/Footer URLs below).

Customizing Header/Footer URLs

To customize the header frame or display a customized footer frame, the properties $JONAS_BASE/conf/jiapadmin_custom.properties file must be edited. This can be done either within the navigational tree by navigating to the Edit Custom Frames link of the Administrator tree, or by manually editing the above properties file.

The following is an example of a configured footer frame, while preserving the default header frame:

# Custom console fields

 

# bottom frame (footer) of the Admin Console.

footer=http://www.somewhere.com/acme.html

# top frame (header) of the Admin Console.

header=

 

It is the responsibility of the administrator to make sure the customized frame content fits within the dimensions of the frame.

 

 


Chapter 3.      User Management

3.1                       Orchestra User Management Basic Configuration

After Orchestra is installed, specific information for user management is stored in the default security Datasource realm, as shown below. This Datasource points to an hsql database, which also contains the Administration console and the Orchestra engine data.

 

Figure 31.    Orchestra User Management Basic Configuration

 

The installation process:

·           Creates and initiates the Datasources (bsoaadmin.properties file created, and Datasource at Orchestra URL populated).

·           Adds the associated Datasource security realm (server.xml and jonas-realm.xml files updated).

This basic configuration can be changed according to specific preferences, for example to use an enterprise Ldap Directory, or to move to another security Datasource realm.


3.2                       Orchestra Profiles

Orchestra users can be granted four different roles covering the main functions of the BPEL management. The following figure shows the scope of each of these roles.

For Orchestra concepts (Process model, Process instances, Process roles, Role Mapper, Performer assignments, activities), refer to the Orchestra Application Programming Interface Guide.

 

Figure 32.    Illustration of Scope of the Orchestra Profile Roles

 

 


3.3                       How To Change the Basic Configuration

Orchestra can be configured to use an internal Datasource or a pre-existing external Ldap database for User Management.

 

Figure 33.    Changing the Basic Configuration for User Management

 

 

 

Orchestra uses the security realm defined at the global context for JOnAS. To change the basic configuration, do the following:

When using another Datasource Security Realm:

·           Create the new database that will be used, and adapt the Datasource description file (bsoaadmin.properties) to the new URL to be used.

·           Initiate this Datasource for correct use with Orchestra (See Section 2.4, “How To Initiate a New Datasource Security Realm for Use by Orchestra”).

When using an Ldap Security Realm:

·           Create the LDAP Directory if it does not exist.

·           Initiate this directory for correct use with Orchestra (See the “How To Configure an Ldap Directory For Use By Orchestra – LoginModule Feature” section).

·           Remember to introduce Orchestra users in it, and to enter each of them in the “Admin” group.


At this point, the JOnAS Application server will use the Datasource or Ldap Security Realm. The last step is to configure Orchestra to use the configured Security Realm for its own user management.

To do this:

·           Use the Process console to change the User Management realm (See the “How To Select a New Security Realm For User Management” section).

·           Stop and Start the JOnAS Server.

Note:

Datasource or Ldap Realm configuration parameters can be accessed and modified by using the JOnAS Admin Console http://Your_Host:Your_HttpPort/jonasAdmin (Domain > Server JOnAS > Security).

Then, for a Datasource Security Realm, the Process Console provides facilities to:

·           Add or Remove users,

·           Modify their profiles within the BSOA scope.

When managing users with an Ldap directory, only the association between users and profiles can be modified through the BPEL Administration Console. Adding or deleting users must be done according to the user-specific Ldap Administration process.

 


3.4                       How To Initiate a New Datasource Security Realm for Use by Orchestra

3.4.1                         Create the Database

If using a new database create it first following your specific Databases administration process.

When using hsql, the database is automatically created when launching the JOnAS application server, if it does not exist.

Adapt the JOnAS Datasource configuration files:

The best way to do this is to keep the default Datasource names in the jonas.properties file (bpel and bsoaadmin), and to modify the properties files (bpel.properties and bsoaadmin.properties) according to the new configuration (changing URL for using a new database, and changing Mapper and Driver for using a new rdbms).

Note:

It is mandatory to keep the JNDI names of these Datasources (bpel and jiapadmin, referenced in the properties files).

The following is an example of the properties files for using a PostgreSQL database, named MyDB.

These files are located under $JONAS_BASE/conf.

Part of bpel.properties file:

   datasource.name         bpel
   datasource.url             jdbc:postgresql://localhost:5432/db_jiapadmin211
   datasource.classname  org.postgresql.Driver
   datasource.mapper     rdb.postgres

Part of jonasadmin.properties file:

   datasource.name=jiap
   datasource.url=jdbc:postgresql://localhost:5432/db_jiapadmin211
   datasource.mapper=rdb.postgres
   datasource.classname=org.postgresql.Driver

The application server must then be stopped and restarted with "Start JOnAS". Remember to put the correct drivers under the $JONAS_ROOT/lib/ext directory. These drivers are located under the bpel/lib/ext directory.

3.4.2                         Initialize the Database(s)

 bpel Datasource: go to the installation directory, and execute the ant initBsoaDb command.

BsoaAdmin Datasource: go to the bsoaadmin directory and execute the
ant –f initJiapDb.xml initJiapDb command.
The databases are then populated with the BPEL and Jiapadmin tables, and the minimum required data.

Note:

Even if a specific Datasource security realm is already being used, the corresponding database must be initialized as described above. Only data contained in Bpel and jiapadmin tables will be available for Orchestra user management.

 

3.5                       How To Configure an Ldap Directory For Use By Orchestra – LoginModule Feature

JOnAS configuration:

Jonas-realm.xml file (path: Orchestra Installation directory \bsoa_base\conf):

The LDAP realm must be described for JOnAS to take it into count. To do this, modify the jonas-realm.xml file (jonas-ldaprealm target) to add the Ldap entry point.

The following is an example of the lines that could be added:

 

<ldaprealm name="ldaprlm_1"

baseDN="dc=frec,dc=bull,dc=fr"

initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"

providerUrl="ldap://localhost:389"

securityAuthentication="simple"

securityPrincipal="cn=admin,dc=frec,dc=bull,dc=fr"

securityCredentials="xxxxxx"

authenticationMode="bind"

userPasswordAttribute="userPassword"

userRolesAttribute="memberOf"

roleNameAttribute="cn"

userDN="ou=jiap_user"

userSearchFilter="uid={0}"

roleDN="ou= jiap _group"

roleSearchFilter="uniqueMember={0}"

referral="throw" />

 


server.xml file (path: Orchestra Installation directory \bsoa_base\conf):

Modify the server.xml file to make it take this new realm into account.

First modify the global realm:

Realm className="org.objectweb.jonas.security.realm.web.catalina55.JACC" debug="99" resourceName="Ldaprlm_1"/>

And change the resourceName field for Bpel Context (path="/bpel"), Bpel Web Services (path="/bpel_ws"),  Bpel Form Generator(path="/formgenerator-1.0" ).

Note:

The Single Sign On (SSO) of Tomcat has been activated.

Jaas.config file (path: Orchestra Installation directory \bsoa_base\conf):

To run the Bpel tests or Bpel samples mentioned in the Orchestra documentation, the jaas.config file must be modified to let jaas know which security resource to use (modify the bpel, TestClient, bpel_policy entries).

Refer to the JOnAS User Documentation for more information about how to modify server.xml and jonas-realm.xml files to introduce a new security realm.

A User Ldap Configuration:

An administrator account that has modify permission to the necessary subTree must be used to update the LDAP directory.

Then, a subtree must be created that will contain the following groups:

JIAPUSER
JIAPOPERATOR
JIAPDESIGNER
JIAPADMINISTRATOR
jonas_admin

All these groups are mandatory for Orchestra, unless using the BsoaLogin Module as explained at the end of this section (JIAPUSER, jonas_admin are no longer required in the Ldap server).

JIAPUSER, JIAPOPERATOR, JIAPDESIGNER, JIAPADMINISTRATOR are managed by the Process Admin Console.


The following is an example of the minimum configuration to import into a user Ldap, based on the previous mentioned Ldap:

 

  dn: dc=frec,dc=bull,dc=fr

  objectClass: top

  objectClass: dcObject

  objectClass: organization

  o: bull

  dc: frec

 

  dn: cn=admin,dc=frec,dc=bull,dc=fr

  objectClass: simpleSecurityObject

  objectClass: organizationalRole

  cn: admin

  description: LDAP administrator

 

  dn: ou=jiap_group,dc=frec,dc=bull,dc=fr

  ou: jiap_group

  objectClass: top

  objectClass: organizationalUnit

 

  dn: ou=jiap_user,dc=frec,dc=bull,dc=fr

  ou: jiap_user

  objectClass: top

  objectClass: organizationalUnit

 

  dn: cn=JIAPUSER,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: JIAPUSER

  uniqueMember: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr

  description: jiap user

  objectClass: groupOfUniqueNames

  objectClass: top

 

  dn: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr

  cn: jiap

  sn: jiap

  uid: jiap

  objectClass: inetOrgPerson

  objectClass: top

 

  dn: cn=JIAPOPERATOR,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: JIAPOPERATOR

  uniqueMember: uid=jiap,dc=frec,dc=bull,dc=fr

  objectClass: groupOfUniqueNames

  objectClass: top

 

  dn: cn=JIAPADMINISTRATOR,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: JIAPADMINISTRATOR

  objectClass: groupOfUniqueNames

  objectClass: top

uniqueMember: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr


 

  dn: cn=JIAPDESIGNER,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: JIAPDESIGNER

  objectClass: groupOfUniqueNames

  objectClass: top

  uniqueMember: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr

 

  dn: cn=jonas-admin,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: jonas-admin

  uniqueMember: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr

  description: jonas administration group

  objectClass: groupOfUniqueNames

  objectClass: top

 

  dn: cn=BPELUSER,ou=jiap_group,dc=frec,dc=bull,dc=fr

  cn: BPELUSER

  description: Bpel Acces Group

  objectClass: groupOfUniqueNames

  objectClass: top

  uniqueMember: uid=jiap,ou=jiap_user,dc=frec,dc=bull,dc=fr

Note:

These entries are mandatory for using the BPEL Engine. To use Bpel, have to introduce Bpel users must also be introduced in the Ldap Directory with the “BPELUSER” role.

After all of this has been done, restart the JOnAS server (bsoap start).


3.6                       How To Select a New Security Realm For User Management

After the previous steps, Orchestra must be configured to modify the User Management configuration.

Orchestra administration

Connect to the Administration console with the appropriate user (Doing this requires an administrator profile. If the basic installation has not been changed, the default login/password (bsoa/bsoa) can be used).

Select the following path in the Navigational Tree (Left Panel): Administrator User Management. The Core Frame (Right Panel) presents the selected and available realms.

 

Figure 34.    User Management Core Frame of Administration Console

 

 


To select a new realm, check the box in front of the appropriate realm in the « Available Realms » list in the Core Frame and click on the « Select the Realm » Button.

A warning is then provided. Confirm your choice by clicking on the “Confirm” Button.

 

Figure 35.    Confirmation Warning When Selecting a New Realm

 

Then stop and restart the JOnAS Server: the new User Management configuration will be available.

Warning:

The User Manager API of Orchestra immediately recognizes these modifications. This can cause problems for running applications. It is strongly recommended to stop and restart the JOnAS server.

 

 


3.7                       How To Access the Description Of a Specific Realm

Select the following path in the Navigational Tree (Left Panel): Administrator User Management. The Core Frame (Right Panel) presents the selected and available realms.

 

Figure 36.    User Management Core Frame Displaying Selected and Available Realms

 

 

Click on the name of the desired Realm. Related information will be displayed in the Core Frame, as shown below for an Ldap Realm.

 

Figure 37.    Display of Information for a Selected Realm

 


3.8                       How To Access the Users List for a Specific Realm

Warning:

This operation can only be performed on the selected security realm (See the previous sections for more information on how to select a specific Security Realm).

Select the following path in the Navigational Tree (Left Panel): Administrator User Management. The Core Frame (Right Panel) presents the selected realm.

 

Figure 38.    User Management Core Frame Displaying Selected Realm

 

Just click on the name of the selected Realm, choose the “Users” tab in the Core Frame, and then click on the “List Users” Button. The users’ list will display under the search panel.

Figure 39.    List of Users for a Selected Realm

 

 

3.9                       How To Add a User To a Specific Realm

Warning:

This operation can only be performed on the selected security realm (see the previous sections for more information on how to select a specific Security Realm) in the case of a Datasource Realm. Ldap Realms must be managed with their specific administration tool.

 

Figure 310.  New User Registration Form

 

First, access the users list of the realm (see “How To Access the Users List for a Specific Realm” section). Then click on the “New user” Button.

The user registration form is shown in the Core Frame. Enter the user information and click on the “Create” button.

For more information on the “Profiles” panel, see the section “How To Access the List of Users Involved In a specific BSOA Profile.”

The user is then added to the security realm.


3.10                 How To Suppress a User From a Specific Realm

Warning:

This operation can only be performed on the selected security realm (See the previous sections for more information on how to select a specific Security Realm) in case of a Datasource Realm. Ldap Realms must be managed with their specific administration tool.

First, access the user list of the realm (see the “How To Access the Users List for a Specific Realm” section). Then check the square in front of the users to be suppressed, and click on the “Remove Users” Button.

 

Figure 311.  Remove Users Form



The users are deleted from the list (replay SEARCH to see it).

 

Warning:

These deletions are effective immediately. This can cause problems for users involved in a current Orchestra process.


3.11                 How To Access the List of Users Involved In a specific BSOA Profile

Select the following path in the Navigational Tree (Left Panel): Administrator User Management. The Core Frame (Right Panel) presents the selected realm. Click on the name of the selected Realm, and choose the “Profiles” tab in the Core Frame. The four profiles are then shown: select one by clicking on it.

 

Figure 312.  List of Profiles for a Selected Realm

 

A new tab is then available in the Core Frame, which lists the users involved in the selected profile.

 

Figure 313.  List of Users in a Specific BSOA Profile

 

To add a user to this profile, select the user in the list by clicking on the user name. The “User xxx” tab will then be shown in the Core Frame. The chosen profile for this user can be selected by clicking first on it in the “Available” panel, then on the  arrow.

To suppress a user from this profile, select the user by clicking on the user name. The “User xxx” tab will then be shown in the Core Frame. The chosen profile can then be suppressed from his list by clicking first on it in the User’s profile panel, then on the  arrow.


3.12                 How To Modify the BSOA Profile or Password For a Specific User

Warning:

This operation can only be performed on the selected security realm (See the previous sections for more information on how to select a specific Security Realm) in case of a Datasource Realm. Ldap Realms must be managed with their specific administration tool.

First, access the users list for the realm (see “How To Access the Users List for a Specific Realm”) and select a user by clicking on his name. The user information form is shown in the Core Frame.

 

Figure 314.  User Information Form

 


To add a profile for this user, first select the profile by clicking on it in the Available panel (on the right), then click on the  arrow. The profile will then be present in the User’s profile panel.

To delete a profile for this user, first select the profile by clicking on it in the User’s profile panel, then click on the  arrow.  The profile will then be suppressed from the user’s profiles.

For other changes, modify user information as necessary.

When finished, click on the “Apply” button to validate the changes.

Warning:

These changes are effective immediately. Changing groups cause problems for users currently running the Process Console.

 


Chapter 4.      Engine Databases

Within this version of Orchestra, only the Bpel Engine is provided. In further versions, a workflow engine will also be included.

The Process console offers a means to access the current Datasource configuration for information only.

 

4.1                       How To Change Basic Engine Datasource

Specifying Datasources (datasource mapper, datasource url, …), is not in the scope of the ACTUAL Process Console.

This is done at installation time and is described in the BPEL installation guide, "Getting Started." This 
guide explains how to adapt jonas.properties and [datasourceName].xml files according to user-specific needs.

To access to the Datasource configuration and to modify the JDBC connection parameters, use the Jonas admin console http://Your_Host:Your_HttpPort/jonasAdmin (Domain Server JOnAS Services Database).

 


4.2                       How To Look at the Engine Datasource Definition

Select the following path in the Navigational Tree (Left Panel): Administrator Engine Databases bpel.

The Bpel Datasource configuration is shown in the Core Frame (Right Panel).

 

Figure 41.    Bpel Datasource Configuration Display

 


Chapter 5.      Editing Custom Properties

Select the following path in the Navigational Tree (Left Panel): Administrator Edit Custom Properties.

The Custom Properties configuration is shown in the Core Frame (Right Panel).

 

Figure 51.    Custom Properties Configuration form

 

To edit the Custom Properties, insert a URL that points to one of the following: a customized file whose content represents an HTML to be displayed in the header or footer frames, a Cascading Style Sheet (CSS), or Extensible Style Language (XSL) definition file. Once the URL(s) are inserted, click the Save button. The administrator will be prompted to confirm the save action. Once the confirmation is performed, refreshing the console () will enable the changes.

 

 

 


Chapter 6.      Setup

Select the following path in the Navigational Tree (Left Panel): Administrator Setup.

The Setup panel is shown in the Core Frame (Right Panel).

 

Figure 61.    Setup Panel

 

This panel provides access to the settings for the Engine Setup and the Monitoring Mode.

Engine Setup:

DB: with this mode, all activities are saved to the database progressively.
Memory: choose this mode for optimum performance of the Orchestra Process Console. Since no backup is made, this option should be chosen for non-critical processes only.

Monitoring Mode:

Nothing: no monitoring at all.
RunningOnly: monitors only executing instances.
MessagesOnly: no monitoring but messages exchanged via the web service are saved.
RunningAndMessages: a combination of the RunningOnly and MessagesOnly modes.
All: all instances are monitored.

A warning is then provided. Confirm the choice by clicking on the “Confirm” Button.