DOWNLOAD Oracle BPM Suite

TAGS BPM, SOA, Middleware, Enterprise Architecture, All Architect Articles

The Oracle BPM Directory Explained

by Mariano Benitez

How BPM Applications use the BPM Directory

Published January 2010

Abstract

This article provides an overview of the Oracle BPM Directory. It will cover basic concepts regarding how BPM Applications use the BPM Directory. The information presented in this article is based on Oracle BPM 10gR3, but most of the content can also apply to Oracle BPM 6.0. Readers should be familiar with Oracle BPM 10gR3 general concepts, including BPM Environment, BPM Engine, BPM Workspace, and process instances. For more information please refer to the product documentation and the companion article, The BPM Environment Explained.

Introduction

The BPM Directory is an information repository. It stores configuration information about a BPM Environment. This repository is a fundamental component of the BPM Environment; a BPM Environment cannot exist without a BPM Directory.

There are several reasons for this:

• All BPM Applications obtain most of their configuration information from the BPM Directory.
  
  
• The BPM Directory provides access to the BPM Organization: participants, groups, Organizational Units, roles.
  
  
• The BPM Directory provides services to identify, authenticate and in some cases authorize participants.

A description of the BPM Directory's integrated in the BPM Environment can be found in The BPM Environment Explained. Additionally, online documentation is available that provides installation and configuration references, as well as simple reference guides.

The Basics

Let's begin by answering the basic questions regarding the BPM Directory.

What is the BPM Directory?

The BPM Directory consists of two components: an information repository critical to the BPM Environment, and an API (called FDI) to access this repository. BPM Applications store most of their configuration information in the repository, and they use the API to access and manipulate the repository.

The repository's logical structure is simply a set of entities. The API provides CRUD operations on these entities. The BPM Directory provides no semantic validation of the entities. Rather, applications that use the BPM Directory validate the information they read and store within it.

All BPM applications share the this API, so they share many features, as well as configuration and runtime tuning.

What is the purpose of the BPM Directory?

The repository contains the following information:

• Definition and configuration of BPM Engines (DB configuration, locations, tuning parameters, threads, etc)
  
  
• Configuration of External Resources (endpoints and URLs for external services)
  
  
• Deployed BPM Projects (processes and the association with BPM Engines and the organization)
  
  
• Other system-wide configuration information (External Processes, BAM, DataMart)
  
  
• BPM Organization information (Participants, Groups, Organizational Units)
  
  
• Process authorization information (Roles and assignments to Participants and Groups)

In addition to its function as an information repository, the BPM Directory is also used to authenticate users attempting to access BPM Applications, and to authorize certain users (BPM Administrators) to manipulate the information in the repository.

What is the composition of the repository?

The BPM Directory normally stores all the information in a single database schema. In some cases, such as when BPM Organization information is externally maintained, the information is obtained via an LDAP server. In such cases, the BPM Directory only reads from LDAP, disabling the functions that update the organization data. LDAP integration is very flexible, allowing different LDAP structures, and allowing all or some of the organization entitites to be obtained from LDAP (Participants, Groups, OUs). In any case, information about Participants and Groups that is not found in LDAP (identification number and role assignments, for example) is stored in the BPM Directory's database schema.

Supported products include major databases (Oracle, DB2, SqlServer, Sybase, Informix), with several configuration options for each, (for example, Oracle RAC). Major LDAPs, including Oracle Virtual Directory, Sun One, Microsoft Active Directory, and Novell eDirectory, are also supported. Web Center Integration (WCI, ALUI) is supported via a Virtual LDAP interface.

The client API (FDI) used to access the BPM Directory repository is pure Java, and requires some configuration files that define the connection properties. From an API client perspective, the structure and backend type of the repository is irrelevant: the information returned by the API is always the same.

The structure of the database schema is very simple, comprised basically of tables, with sequences for unique identifiers and triggers to audit the creation and update time of some tables. No stored procedures or views are defined in the schema.

Who/What Uses the BPM Directory?

Every BPM Application uses the BPM Directory, most importantly BPM Engines, all PAPI clients (including the BPM Workspace, PAPI-WS), and the Process Administrator.

The Java API's architecture is very similar to a JDBC driver: there is no central Directory Service to serve repository access requests. Every application accesses the repository (database schema and LDAP) directly through the API.

Setup

Now let's cover how the repository is initialized, and then look at how the applications are configured to access the repository.

Since the BPM Directory is the core of BPM Environments, setting up a new BPM Directory is actually the first step in the creation of the BPM Environment. This action is divided in two important steps:

1. Creating a new repository
   
   
2. Configuring applications to use the new repository.

Creating a BPM Directory Repository

This first step is critical: without a repository there is no BPM Environment. This step creates and seeds a new database schema, and prepares it to contain the new BPM Directory repository. It also creates a new configuration file, which applications can then use to connect to the new BPM Directory repository.

At this stage, important architectural decisions are made, including database vendor and location, LDAP integration, and connection properties.

BPM Directory repository configuration options

The configuration options available when the schema is created cover different areas, for example:

• Database schema: vendor and connection information (data and temporary tablespaces) used to create the schema and then connect and seed the tables.
  
  
• Database runtime: credentials, connection pools and other runtime parameters, including open cursors and connection idle time.
  
  
• LDAP integration: connection information and the mapping between the LDAP true structure and the BPM organization model (for example, base DN and queries to retrieve users). There are also parameters to customize the entitites to obtain from LDAP (for example, "use only LDAP users, but not OUs").
  
  
• LDAP runtime: credentials, connection pools and other runtime parameters (for example, connection idle time, LDAP referrals)

In addition to these basic values, any provider-specific property can be included. All this information is stored in the configuration file that will then be used by BPM applications.

Configuring Applications

BPM Applications are part of a specific BPM Environment, as identified by the repository to which they are connected. The configuration file created in the previous step is used to establish the connection to the repository.

BPM Applications can obtain the configuration file in a variety of ways. For instance, WAR or EAR files into which some applications are bundled typically include the configuration file, as is the case with the BPM Engine running inside WebLogic. Other applications read the file directly from the file system, as is the case with a standalone PAPI application.

Another option for connecting to a repository is to include all the information normally found in the configuration file as arguments when the FDI Service is initialized. This approach does not use a configuration file, and is sometimes used in Java applications when the connection information is stored elsewhere.

The configuration file can be obtained in three different ways: from the file system, as a classpath resource, or as a URL. While each way is suitable for different use cases, certain defaults may apply to each BPM Application. The choice to use the default locations or change them is a matter of architecture and design.

All BPM Applications define the location of the directory configuration file in their own application configuration file, and the defaults are easy to use.

• Example #1: The BPM Workspace configuration file is called workspace.properties. Within that file you can change the location of the BPM Directory configuration file. The default location is WEB-INF/directory.xml, inside the application WAR file.
  
  
• Example #2: Experienced architects who frequently change config parameters may choose to configure all applications to obtain the configuration file from a URL. Obviously, if you want to change a parameter in a config file bundled inside a EAR file, you need to rebuild the EAR and include the modified file.

Extending the initial configuration

When the BPM Directory repository is created, a single database user is created to connect to the database. Let's call this user the repository owner. This user is used by all BPM Applications that were configured during the repository creation. The repository owner has read/write permissions on the entire BPM Directory repository database, so it is important to secure the information in the configuration files, especially since the database user and password is contained in those files.

Now let's take a look at some configuration options for extending security and/or administration.

Using a different database user to connect to the BPM Directory repository

It is possible to create a new database user with fewer permissions than the repository owner in order to prevent unauthorized changes in the event that the BPM Application or the configuration file are compromised.

Setting up a new database user is a manual process, comprised of the following steps:

1. Create the database user and assign the desired permissions on the repository schema.
   
   
2. Create a new configuration file by modifying the initial file to reflect the new connection information.
   
   
3. Copy the new configuration file to the desired BPM Application, regenerating the War/Ear files as necessary.
   
   
4. Update the "Trusts" repository to allow the new database user to use the FDI Service (more on this below).

For more information on this procedure, please refer to Oracle BPM Advanced Articles and Topics.

Allowing other database users to use the FDI Service

When BPM Applications initialize the FDI Service, the current database user is verified to be allowed to initialize the FDI Service. This check is performed against a repository table called "Trusts". The Trusts table is managed by Ant Tasks, but it is also possible to update the repository table directly.

The Trusts table also indicates whether BPM Participants are always required to authenticate, or they are allowed to skip authentication in order to use the BPM Directory repository. This setting is important when Single Sign-On will be used in a BPM Application. This setting can be applied globally or individually to BPM Participants.

For more information on the Ant Tasks, please refer to the Ant Tasks Reference.

Specifying the BPM Participant accessing the BPM Directory repository

A BPM Participant must be specified in order to use the BPM Directory repository. Specifying the BPM Participant identifies the individual who will perform the operations and grants the appropriate authorization. In the case of an end-user application, such as the BPM Workspace, the BPM Participant is the browser user, who enters his/her own credentials. In the case of a backend application, such as the BPM Engine, the BPM Participant is specified in the BPM Directory by presets in the configuration file.

These presets specify the BPM Participant that will perform the operations when the preset is used. Presets for different applications are included in the configuration file that is generated when the BPM Directory repository is created.

Runtime

Now that BPM Applications are configured to use the BPM Directory, let's cover the runtime behavior of these applications.

During runtime, when BPM Applications require information from the BPM Directory, they access the repository using the BPM Directory API (FDI).

In order to use this API, applications must first initialize the FDI Service, using the information from a configuration file. Once the FDI Service is initialized, applications can use the service to access the BPM Directory repository.

How does the BPM Directory API accesses the repository?

From a low-level connectivity point of view, the BPM Directory API uses standardar JDBC connections and pure SQL statements to access and manipulate the repository schema. In the case of LDAP integration, the BPM Directory API uses JNDI contexts with simple LDAP queries. Both database and LDAP connections are created and/or obtained based on the information contained in the configuration file (directory.xml).

When BPM Applications are deployed in a J2EE Application Server (e.g. WebLogic), JDBC connections are normally obtained from JDBC datasources defined and configured in the J2EE container. In the case of standalone Java applications (e.g. a Standalone BPM Engine or a client java application using PAPI), connections are created and maintained by the FDI Service. In this case, connections (both database and LDAP) are internally cached by the FDI Service in order to optimize response times,. The size of these caches is also defined in the configuration file.

It is important to remember that all BPM Applications will require network access to the database and LDAP servers they are configured to work with.

What can be done with the BPM Directory API?

• Access to the BPM Directory repository
  The API provides a unified view of the information stored in the repository, independent of the repository's physical characteristics. For example, BPM Applications will retrieve Participant entities, regardless of whether they are obtained from the database or LDAP. The API provides basic manipulation methods for all the BPM Directory entities (ranging from Participants and Groups to Process Definitions and BPM Engine configurations).
  
  Given the different options for LDAP integration, the BPM Directory will disable some update operations based on the capabilities of the underlying infrastructure, . For example, update of Participants is disabled in some LDAPs, since the underlying LDAP system doesn't support it. These capabilities can also be disabled via configuration (for example, disable reading OUs from LDAP).
  
  
• Listen to changes in the BPM Directory repository
  Since BPM Applications obtain very important information from the repository, the must sometimes react to changes in the repository.. For example, if a new Participant is added to the repository, the BPM Workspace must allow assigning instances to the new user. Similarly, if role assignments for a group are changed, the BPM Engine must update permissions on all participants assigned to the group, and eventually reassign instances if a participant no longer has the appropriate permissions.
  
  This is an important function of the API. BPM Applications are optimized not to query the BPM Directory repository for every request, so they need a way to receive notification of changes in the repository.
  
  
• Authentication of BPM Participants The authentication of BPM participants is another important function. End-user access to applications, such as the BPM Workspace (or any PAPI client), is granted only after proper indentification and authentication. The BPM Directory API provides a way to validate that credentials entered by the end-user are correct and correspond to a valid participant in the BPM Organization. Participant information is returned after authentication, allowing BPM Applications to use information for the connected participant.
  
  BPM Applications are responsible for collecting the credentials (by asking username/password, for example). These credentials are then validated by the API. If the authentication is successful, access to the application is granted.
  
  The Username/password combination is the only authentication method internally supported by the API. When the participants are stored in LDAP , this validation method has a different implementation. When participants are stored in the repository database, passwords are hashed and compared with the value stored in the participants table. With LDAP, a new JNDI context is created using the configured LDAP URL and the received credentials.
  
  When Single Sign-On (SSO) is configured in an application, the API performs no authentication. Instead, it validates that the supplied identification (participant id) corresponds to valid participant. In this case, BPM applications or the container are responsible for authenticating the end-user. We will cover SSO in more detail later in this document.
  
  
• Authorization on repository operations
  In addition to role-based authorization for BPM Processes (which is the responsibility of the BPM Engine) there is another authorization model that protects certain operations on the BPM Directory repository. These operations include modifying the BPM Engine configuration, publishing BPM processes, or creating participants.
  
  These operation are allowed only to participants with an administrator profile. This profile is required to access BPM Process Administrator, for example.
  
  The API will validate that the connected user is an administrator before executing these operations, rejecting the operation if the validation fails. The administrator profile is part of the available information on participants, enabling or disabling actions based on this information.
  
  

How BPM Applications use the BPM Directory?

Different BPM Applications use the BPM Directory in different ways, depending on their specific characteristics. Variations in usage can also appear when applications initialize and during normal operations.

The following section describes how some BPM Applications use the BPM Directory.

The BPM Engine

The BPM Engine makes the most use of the BPM Directory, but the usage is not very heavy. The basic uses are listed below:

On startup the application reads and keeps in memory:

• Its own configuration information (listening ports, database connection information, services, threads, etc)
  
  
• Configuration for External resources used by BPM Processes (web service endpoints, external databases, etc)
  
  
• The definition of BPM Processes deployed in the BPM Engine
  
  
• A full load of OUs, groups and calendar rules
  
  
• A partial load of participants.

During normal operation:

• Loads participant information as needed (when they login or as the result of a participants query)
  
  
• Listen to changes among participants and groups (looking for changes in role assignments).

The BPM Workspace

The BPM Workspace uses the BPM Directory very frequently. This usage is representative of any PAPI based application, such as PAPI-WS or any standalone Java client. This usage is described below:

On startup read and keep in memory:

• A partial load of groups and participants
  
  
• All existing BPM Processes deployed in the BPM Environment

During normal operation:

• Authenticate participants upon login using the provided credentials (if so configured)
  
  
• Load participant information as needed
  
  
• Listen to changes among participants and groups
  
  
• Search participants by name, or assigned to a role

BPM Directory Repository Performance

As is the case when using any remote resource, accessing the BPM Directory repository is an expensive operation. It is therefore important to understand which operations have the most impact on each BPM Application. There are only a few operations that are important to monitor, among them the initial load of participants, and generating the list of changes on participants and groups.

Monitoring the initial load of participants can be a lengthy process, depending on the number of elements to load, the total number of participants, and in the case of LDAP, the time it takes to execute the LDAP query.

Getting the list of changes in the repository is also a critical and potentially time-consuming process. Queries against entities stored in the database are filtered by the modification time column in the tables. In the case of LDAP entities, the queries use the modification attribute on the entries.

The BPM Organization

The BPM Organization defines how BPM Applications view the enterprise organization. The following section describes the BPM Organization model, how it is used, and the mapping between the enterprise organization and the BPM Organization.

The BPM Organization Model

Oracle BPM defines its organization model using a few concepts, or entities, along with their relationships. Certain critical features depend on the BPM Organization model. BPM Process Authorization is one such feature. Security and/or authorization issues may arise if the organization is not accurately reflected in the system. The entities and their rules are described below.

The BPM Organization entities:

• Participants
  
  
• Groups
  
  
• Organizational Units
  
  

The BPM Organization rules:

• Organizational Units (OUs) are defined as a hierarchy, with the Organization as the root OU
  
  
• Participants can belong to only one Organizational Unit
  
  
• Participants can belong to one or more Groups. Groups can belong to other groups.

Mapping the Enterprise Organization to the BPM Organization

The enterprise organization must always be mapped to the BPM Organization. This mapping is a central issue in the definition of the BPM Environment because it defines how the enterprise organization entities, such as users and groups, are reflected in Oracle BPM. Every enterprise defines its own organization model, as determined by enterprise requirements, policies, and dynamics. The mapping process must be reviewed in every case.

The mapping between the enterprise organization and the BPM organization is divided into static and dynamic aspects, as described below.

The Static Aspect of BPM Organization Mapping

The static aspect refers to how entities in the enterprise organization are converted into BPM entities. For example: only certain users in the enterprise organization will be listed as Participants in the BPM Directory, such as users with certain LDAP attributes. We refer to this aspect as static since it is defined before the BPM Environment is created, and it applies throughout that environment's lifespan. This static mapping must be defined for every BPM Organization entity (Participants, Groups, and Organizational Units) regardless of whether there is LDAP integration.

The Dynamic Aspect of BPM Organization Mapping

The dynamic aspect refers to how changes in the enterprise organization are reflected in the BPM Directory. This includes adding, updating, and deleting Participants and Groups. BPM Applications must quickly detect and react to these changes, since they definitively affect the BPM Process permissions assigned to users.

Enterprise Organization Mapping Examples

While each enterprise must define its own organizational model, most organizations fall within a few prototypical cases, as described below. These cases are provided to aid in the identification of the appropriate mapping for your organization.

• No Integration
  In this case, BPM users, groups, and OUs are managed via BPM tools, such as BPM Process Administrator. No external source of organizational information is available to the BPM Directory.
  
  The initial seeding of the organizational information (Participants, Groups, OUs) is typically preformed manually by the admins before the production launch.
  
  Authentication is typically performed by BPM Applications, using username and passwords. If SSO is enabled, it is critical that the Participant IDs created in the BPM Directory repository match the SSO username.
  
  This case is common for small departamental environments where integration with corporate directories is neither required nor desired. This case may require duplicate management if there is another organizational repository, and there is no automatic synchronization of the repositories.
  
  
• Integration with LDAP
  When an enterprise already uses LDAP for the corporate directory, it is useful to integrate it with BPM Directory. The main benefit is that there is no duplicate management of users and groups. In this case, the key issue is the definition of the LDAP queries and attributes that are mapped to the BPM Organization (Participants, Groups, OUs).
  
  The LDAP queries are defined inside the BPM Directory configuration file when the BPM Directory repository is created. Oracle BPM provides sample LDAP configuration files for each LDAP-supported product. These samples follow the default organization configuration of the LDAP products, so some modification may be necessary in order to meet the your organization's specific needs. Organizational information is initially seeded when the BPM Directory repository is created. This process traverses all LDAP Participants and creates the corresponding database entries for each.
  
  Organizations with more than ten thousand users must pay special attention to LDAP queries, since they can significantly slow the performance of BPM Applications.
  
  
• Synchronization with Third Party Systems
  This case applies when an automatic synchronization procedure is used to copy the organization from a third party system into the BPM Directory repository. This happens, for example, when an enterprise manages the organization with an application that does not support LDAP.
  
  Typlically, a scheduled job will read from the external system and reflect the changes in the repository. One option is to trigger a synchronization job every time a change occurs in the external system. Either option is valid; the choice depends on the complexity of implementation.
  
  There are several option for creating the elements in the BPM Directory repository, depending on how the procedure is written. When using pure Java, the BPM Directory API (FDI) can be used. For a BPM Process, BPM Directory components (FuegoBlocks) are available.
  
  Syncronization requires an initial seeding of the repository. Depending on the specifics of your situation, this may occur the first time the sync job is triggered, or the seeding may have to be run separately.
  
  

The BPM Process Authorization Model

The BPM Process Authorization model allows Participants to interact with BPM Processes. This is the entitlement model that is enforced by the BPM Engine on every process-related action. There are two aspects to this model: Visibility and Permissions. Participants are allowed to interact with Processes only when they have both visibility into the processes and permission to interact with them. The Visibility concept works by showing or hiding entire processes based on the rules. The Permissions concept works by enabling actions inside a process based on the roles assigned to the participant.

BPM Process Visibility Rules

The following guidelines define when a Participant will have visibility on a Process.

• Processes are deployed to one or more OUs.
  
  
• Processes deployed in the root OU are visible to all Participants.
  
  
• Participants that belong to the root OU have visibility on all Processes.
  
  
• Participants have visibility on Processes deployed in the Participant's OU or in any "child" OUs.
  
  
• Participants have visibility on Processes deployed in the path from the Participant's OU to the root OU.

BPM Process Permissions Rules

The following rules define when a Participant will have permissions to interact with a Process. Permissions are based on Roles, as , and how they are assigned to Participants and associated with Process Activities.

• Roles can be assigned to Participants or Groups.
  
  
• Roles assigned to a Group are inherited by Participants and Groups that belong to that Group.
  
  
• Every Process Activity is associated with a single Role.
  
  
• A Participant has permissions for the activities that are associated with Roles to which the Participant is assigned.
  
  
• Some Process-level operations require Participants to have at least one Role used inside the Process.

Single Sign-On and the BPM Directory

In this section we briefly explain how Single Sign-On (SSO) affects the BPM Directory. More in-depth information on the use of the SSO framework in Oracle BPM Applications, on enabling SSO, and on customizing SSO plugins will be provided in a future article.

From a BPM Directory perspective, enabling SSO for a BPM Application simply means that the application will skip authentication because there is no need to authenticate the identity of the BPM Participant. In this case, the only validation performed is matching the identification received with an existing BPM Organization Participant.

From the BPM Directory point of view, enabling SSO requires special settings both in the API and in the repository. This settings can be done manually or they can be performed automatically as part of the BPM Directory repository creation wizard, by setting the SSO checkbox during the wizard configuration.

This assumes that the appropriate authentication frameworks are in place, provided by the application or the container. The BPM Applications will also need to obtain the identification information provided by the authenticating module.

Skipping Authentication in the BPM Directory API

During runtime, the BPM Directory API is responsible for authentication. In certain situations, however, this function is unnecessary. To instruct the API to skip authentication, a special keyword, called "skip-auth", must be included either in the configuration file or in the runtime connection properties.

As previously described, the "Trusts" table in the repository is used to verify that the current database user is allowed to use the repository. This verification is different when the "skip-auth" flag is set, requiring an additional permission to skip authentication to be set. A BPM Participant cannot skip BPM Directory repository authentication unless this is enabled in the "Trusts" table.

What's next?

This article provided a broad overview of topics related to the BPM Directory. Subsequent articles will cover other major topics, including the BPM Engine, Security, and BPM Applications.