| Architect: BPM
The Oracle BPM Directory Explained
by Mariano Benitez
How BPM Applications use the BPM Directory
Published January 2010
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.
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:
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.
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:
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.
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:
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:
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.
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.
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:
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.
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?In addition to accessing the BPM Directory repository, which is its core function, the API provides other important functions. These include:
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:
During normal operation:
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:
During normal operation:
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:
The BPM Organization rules:
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.
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.
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.
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.
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.
Mariano Benitez, a BPM Architect for Oracle, has been building BPM software for more than seven years, and has been involved in various aspects of IT, including developement, mangagement, sales engineering, professional services, and support.