This chapter describes Oracle Communications Billing and Revenue Management (BRM) LDAP Data Manager, its API and mapping files, its predefined mapping schemes, the BRM LDAP object model, the channel framework, and the replication module.
The LDAP Data Manager translates the BRM object model to the directory server object model. It implements a subset of the standard BRM object API.
You can think of the mapping task between BRM and your directory server in these terms:
At the lowest level, you map BRM fields to directory server attributes.
At the next level, you map BRM classes to directory server objects.
At the highest level, you determine the mapping scheme to use for your directory server, for example, the user mapping scheme or the one-to-one mapping scheme.
The next sections describe the LDAP Data Manager API, in particular, the data types, the LDAP mapping files, class and subclass mapping restrictions, required fields, base class attributes, as well as LDAP Manager supported and unsupported operations.
BRM accesses all attribute values as UTF8 strings in the directory server. You can encode the following BRM field values as strings:
PIN_FLDT_INT, PIN_FLDT_ENUM, and PIN_FLD_DECIMAL are encoded as the decimal representation of their values, with each decimal digit represented by its character equivalent. For example, the number 1234 is represented by the character string 1234.
PIN_FLDT_POID and PIN_FLDT_STR are encoded as is.
PIN_FLDT_TSTAMP is encoded as the string representation of the UTC time value. By default, time stamps are encoded in their decimal format.
Note:
You can also represent time stamps as printable strings in a more readable format. For more information, see "Configuring the Connection Manager for LDAP Manager".PIN_FLDT_ARRAY fields are mapped to multivalue attributes.
Note:
The array elements must each have only one field and the element-id is not significant. Arbitrary BRM arrays are not supported.PIN_FLDT_BINSTR fields are encoded using base-64 encoding and stored as binary values.
PIN_FLDT_SUBSTRUCT, PIN_FLDT_BUF, PIN_FLDT_OBJ, and PIN_FLDT_ERR type fields are not supported.
The LDAP Data Manager mapping file specifies the BRM data elements to replicate in your directory server. The mapping file maps:
BRM classes to directory server classes.
BRM objects to directory server entries.
BRM fields to directory server attributes.
Figure 2-1 shows snippets of the BRM LDAP flist, the mapping file, and the directory schema and how the components correspond to each other:
Figure 2-1 BRM LDAP Flist, Mapping File and Directory Server Entries
When you install LDAP Manager, a sample mapping file (BRM_Home/sys/ldap.idl) and the LDAP Data Manager configuration file (BRM_Home/sys/dm_ldap/pin.conf) are included with your installation. You use the ldap.idl mapping file to define your BRM LDAP mapping configuration.
The mapping file needs to match your directory server implementation. The mapping file specifies this information for each object type:
Mapping from BRM fields to LDAP attributes, permission for attributes (mandatory/optional/system), and modify permissions (readable/writable).
Absolute Distinguished Name (DN) suffix, which determines the location of the entry for replication purposes.
For more information on how BRM composes the DN when it creates objects, see "About Managing Directory Server Entries".
In some cases, after you set up your mapping file, you might want to override the location value in the mapping file by using BRM LDAP DN qualifiers or location parameters. For more information, see "Specifying Directory Tree Entries".
BRM field for the Relative Distinguished Name (RDN) of the entry. The LDAP Data Manager uses the RDN when you do not specify a DN during creation of the entry.
Important:
BRM does not support RDNs composed of multiple attributes within the entry. Only one top-level, non-array field in the base class can be tagged as an RDN component.ObjectClass of the entry that corresponds to the object type.
Ordered list of LDAP attributes with explicit values that are passed along when you create the entry. This is useful in LDAP environments that use inherited object classes.
In addition to the mapping file you create, you must configure the following directory server information in the LDAP Data Manager pin.conf file:
Directory server port and location
Directory server bind information
Directory server password information
Queue-based daemon parameters
The LDAP Data Manager authenticates itself by using a clear password (simple authentication). BRM binds to the User ID and password that you set up for your directory server. For more information on configuring BRM and LDAP components to communicate with each other, see "Installing LDAP Manager".
The LDAP Data Manager uses the interface description language (idl) format to map BRM classes, subclasses, and fields to directory server entries.
The LDAP Data Manager parses the mapping file when it starts. BRM determines the location of directory server entries from the mapping file for replication purposes.
Figure 2-2 shows parts of the class definitions you can create and their corresponding implementation values:
Figure 2-2 Class Definitions and Corresponding Implementation Values
This has two sections:
Class definitions specify the required and optional fields, the permissions for fields (read/write), and the length for string fields.
Implementation definitions specify directory server object classes, base location in the directory tree, attribute names for fields, and how to compose a Distinguished Name (directory's object id).
The following restrictions apply to the classes and subclasses you define in the mapping file:
Only one non-array required field in the base class can be tagged as RDN_PIECE.
Only a field within an array can be tagged MULTIVALUED.
Required fields in the base class:
PIN_FLD_POID
PIN_FLD_MOD_T
PIN_FLD_CREATED_T
Attributes that apply only to the base class:
ENTRY_TYPE
ATTRVAL
The LDAP Data Manager uses LDAP-specific inputs and outputs to opcodes that perform operations on a base BRM system. Therefore, if you have experience customizing BRM, calling the LDAP Data Manager opcodes is similar to calling the Oracle Data Manager (dm_oracle) opcode.
Use the BRM and LDAP Data Manager API opcodes to perform the following data propagation tasks:
Create entries in the directory server.
Modify entries in the directory server.
Delete entries in the directory server.
Delete attributes from the directory server entry.
Read entries from the directory server.
Read attributes from an entry in the directory server.
Search for entries in the directory server.
Verify that the LDAP Data Manager and the directory server daemon/service processes are up and running and communicating with each other.
For more detailed information on these operations, including their inputs and outputs, see "LDAP Base Opcodes" in BRM Developer's Reference.
For more information on working with directory server entries, see "About Managing Directory Server Entries".
LDAP Data Manager does not support transaction operations (PCM_OP_TRANS_*).
The purpose of the mapping scheme is to replicate BRM data to your directory server. The LDAP Data Manager provides you with the following predefined mapping schemes:
user mapping scheme - Maps BRM /account and /service objects to one entry in the directory server.
one-to-one mapping scheme - Maps BRM /account and /service objects to separate entries in the directory server.
For a procedure overview of how to use the user mapping scheme, see "Defining the User Mapping Scheme". For a procedure overview of how to use the one-to-one mapping scheme, see "Defining the One-to-One Mapping Scheme".
Before you map BRM objects to directory server entries, you need to understand the BRM object model. The next sections describe the BRM object model and how BRM translates its data elements to directory server entries.
Both the user mapping scheme and one-to-one mapping scheme use a replicatable user object (/r_user) class to propagate BRM information to the directory server. The /r_user object is not an actual BRM object, but rather, an object type definition that allows the LDAP Data Manager to translate directory server information into a format that BRM can understand.
BRM objects that are replicated to the directory server are called replicatable objects. These can be virtual objects defined just for replication; these objects do not necessarily exist in the BRM database.
The only requirements for these replicatable objects are that they have a unique Portal object ID (POID) and that they are replicated intact to external sites. Reasons for the whole replication are:
To preserve the object interface
To simplify mapping to and from external implementations
For more information on BRM data types and the POID, see "Understanding the BRM Data Types" in BRM Developer's Guide.
A replica object is a subset of the corresponding BRM /account and /service objects that you define. By default, the /r_user replica object includes a number of the fields that make up the /account and /service objects as defined in the ldap.idl mapping file.
The replica contains enough information to point to the corresponding replicatable object, but with object IDs that are different from those of the replicatable objects. The object types must be the same.
BRM maps replicas to entries in the directory server, and these entries have a pinpoid directory attribute that holds the replica object ID.
Because you cannot represent the entire /account object in the directory server, it cannot serve as a replicatable object. To locate the /account object easily, BRM creates a replicatable object with the same POID as the /account object, but with a different type.
For example, if you use the one-to-one mapping scheme for translation purposes, the POID of the replicatable object, such as 0.0.0.1 /r_account 455, is used to create a replica with the object id 0.0.5.X /r_account 455, where the first part of the POID is the LDAP Data Manager database number and X is the number of the Oracle database.
Figure 2-3 shows the BRM replication scenario for both the user scheme and the one-to-one mapping scheme.
By default, BRM propagates changes to the directory server by using the channel framework. You can configure BRM to export data serially or in parallel. The default is serially.
Figure 2-4 shows the BRM channel framework data flow:
Figure 2-4 BRM Channel Framework Data Flow
As changes take place within BRM through a client application (driver application), such as the addition of a new account or service, a transaction occurs within BRM and is captured as an event. After you commit the changes to the BRM database, BRM pushes the changes to the specified LDAP Data Manager in near real-time.
BRM uses the /channel object to store configuration information for BRM channel events. A channel determines how a set of events gets published to an LDAP directory server. Channels also organize what data is transferred between the BRM database and the LDAP database by defining suppliers and consumers:
Suppliers (PIN_FLD_SUPPLIER_OBJ) contain information about the BRM object that triggered the creation of the /channel_event object. A channel definition can contain any number of suppliers.
Suppliers include the BRM database number in which the event occurred and the BRM object name. For example:
0.0.0.1 /account
When an event occurs in the BRM database, the PCM_OP_CHANNEL_PUSH opcode searches for all suppliers and returns a list of the channels that contain them. For each channel retrieved, it creates one /channel_event object in the BRM database. This handles the case in which the same supplier is associated with multiple channels.
Consumers (PIN_FLD_CONSUMER_OBJ) accept change information from suppliers, translate the change information, and call the LDAP Data Manager to propagate the changes to the directory server.
Consumers include the LDAP Data Manager (DM) to which the Connection Manager (CM) connects and the destination object name. For example:
0.0.5.1 /r_account -1
Each consumer is coupled with a reference to an opcode (PIN_FLD_PUSH_OPCODE field) that publishes the object data to the directory server. For example, 745 is the opcode reference to the PCM_OP_REPL_POL_PUSH policy opcode, which is the default push opcode.
Channels act as reliable message queues and provide retry capabilities.
The /channel object contains the following information:
Channel ID
Description
Channel family
Channel order
List of suppliers
List of consumers and a per-consumer push opcode
For an example channel definition, see "Example channel_config.xml File".
BRM uses /channel_event objects to track changes to a specific consumer. For example, BRM creates a channel_event entry to indicate that a billing type change was made.
The /channel_event object contains the following information:
Channel ID
Channel event ID
Source ID
Supplier ID
Status
Each /channel_event represents a unit of work that needs to be propagated. It contains a pointer to the object that generates the change (SOURCE_OBJ).
A channel family is a channel attribute that enables you to create independent groups of channels that get handled separately by the channel framework. You define a family by setting the PIN_FLD_FAMILY_ID value in the /channel object.
To retrieve channel events for a channel family, run the pin_channel_export utility with the -f parameter and specify the family ID. When the pin_channel_export utility runs, it retrieves the channels containing that ID and then determines how to process the channel events based on their channel definitions.
Note:
A channel definition can have only one channel family value. Within that family, all channels are published according to the channel priority, if defined. For more information, see "About Channel Order".For more information on assigning a channel family, see "Configuring Channel Definitions".
For information on how the pin_channel_export utility works, see "How Channel Events are Published".
The channel order defines the sequence in which channels with the same family ID are processed. The publishing order is ascending, with 1 being the highest priority. You define the channel order by setting the PIN_FLD_CHANNEL_ORDER value in the /channel object.
When the "pin_channel_export" utility runs, it reads the channel definitions in that family and prioritizes them based on their channel order. For example, consider the channel IDs 10, 20, 30, and 40 in family 100 shown in Figure 2-5:
Figure 2-5 Example Channel IDs for Family ID 100
Because channel 30 is an account creation channel event, its order is set to 1 so it will be created in the LDAP database before any modification events associated with the account are published. Channel 10, which contains account modification suppliers, is published next. Channel 20, the service creation channel, is ordered after the account creation channel but is published before the service modification channel 40 as depicted in Figure 2-6):
Figure 2-6 Example Publishing Order for Family ID 100
When the pin_channel_export utility runs, it first retrieves batches of /channel_event objects belonging to channel 30 and publishes them, then it does the same for channels 10, 20, and 40, in that order.
Note:
You can also set the publishing priority to 0, which is the default. In such cases, the channels are published in increasing order of their channel IDs.For information on assigning a channel order, see "Configuring Channel Definitions".
For more information on how channel events are published, see "How Channel Events are Published".
You can define whether channel events are published to an LDAP server serially (0, the default) or in parallel by setting the PIN_FLD_MULTI_THREADED value of the /channel object. When you set the value to 1, all channel events with that channel ID are published concurrently.
For example, say channel ID 30 has a PIN_FLD_MULTI_THREADED value of 1 and channel ID 20 has a PIN_FLD_MULTI_THREADED value of 0. When the pin_channel_export utility runs, it processes the channel events for channel ID 30 in parallel because the publishing mode is set to multithreaded (1) as shown in Figure 2-7:
Figure 2-7 Multithreaded Publishing Example for Family ID 100
It processes channel events for channel ID 20 one after another because the publishing mode is set to serial (0) as shown in Figure 2-8:
Figure 2-8 Serial Publishing Example for Family ID 100
For information on assigning a publishing order, see "Configuring Channel Definitions".
For more information on how channel events are published, see "How Channel Events are Published".
By default, you define channels in the BRM_Home/sys/data/config/channel_config.xml file. This configuration file contains one or more channel definitions that get stored in the /channel object. Each channel definition is defined in the file as a Channel child element of the ChannelConfig parent element.
Table 2-1 describes the elements and attributes in the Channel child element and shows their corresponding fields in the /channel object.
Table 2-1 Channel Elements and Attributes with Corresponding Fields in the /channel Object
XML Field | /channel Object Field | Description | Possible Values |
---|---|---|---|
FldChannelId |
PIN_FLD_POID |
A number that identifies the /channel object in the BRM database. |
Any positive integer less than 1000. Channel IDs 100-103 are pre-defined but can be customized. |
FldName |
PIN_FLD_NAME |
An optional character string that provides a descriptive name for the channel. |
The name must be unique within your BRM system. Minimum length is 1 character; maximum length is 255. |
FldFamilyId |
PIN_FLD_FAMILY_ID |
A number that identifies the family ID. Channels with the same family ID are processed as an independent group. |
Any positive integer. 0 - Disables the family functionality. |
FldOrder |
PIN_FLD_CHANNEL_ORDER |
The publishing order of the channel in a family, in ascending order. If two channels in the same family have the same channel order, the behavior is considered undefined. |
Any positive integer. 1 - The highest priority. 0 - The default, which sets the order as undefined. Channels are published in increasing order of their channel IDs. |
FldMultithread |
PIN_FLD_MULTI_THREADED |
Specifies if the channel should be published serially or in parallel. |
0 - Publish channels serially. 1 - Publish channels in parallel. |
FldSupplierObj |
PIN_FLD_SUPPLIERS |
An array that holds information about the suppliers. |
The array element ID must be 1. |
FldDatabase |
PIN_FLD_SUPPLIER_OBJ |
The BRM database number. |
The BRM database number (FldDatabase) and the supplier event name (FldSupplierName). The format is database_number/object_name. |
FldSupplierName |
PIN_FLD_SUPPLIER_OBJ |
The name of the supplier object. |
The BRM database number (FldDatabase) and the supplier event name (FldSupplierName). The format is database_number/object_name. |
FldConsumerObj |
PIN_FLD_CONSUMERS |
An array that holds information about the consumers. |
The array element ID is not significant. |
FldDatabase |
PIN_FLD_CONSUMER_OBJ |
The LDAP database number. |
The LDAP database number (FldDatabase) and the consumer name (FldConsumerName). The format is database_number/object_name. |
FldConsumerName |
PIN_FLD_CONSUMER_OBJ |
The name of the replicatable object in the LDAP database. |
The consumer object is comprised of the LDAP database number (FldDatabase) and the consumer name (FldConsumerName). The format is database_number/object _name. |
FldPushOpcode |
PIN_FLD_PUSH_OPCODE |
The number of the opcode that is used to publish information to the LDAP database. By default, this points to the PCM_OP_REPL_POL_PUSH policy opcode. |
Any positive integer. |
After editing the contents of the XML file, you use the "load_channel_config" utility to load the contents of the file into the /channel object in the database. Before loading the contents of the file, the utility validates the contents against the file's schema definition. If the contents do not conform to the schema definition, the load operation fails.
By default, the schema definition is located in the BRM_Home/xsd/channel_config.xsd file.
Important:
The channel_config.xml file must follow all standard XML formatting rules.The following example shows a typical channel_config.xml file. It defines two channel families, 100 and 200, and eight channels: 10, 20, 30, 40 in family 100, and 50, 60, 70, 80 in family 200.
<?xml version="1.0" encoding="UTF-8"?> <ChannelConfig xmlns="http://www.portal.com/schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig channel_config.xsd"> <Channel FldChannelId="30" FldFamilyId="100" FldOrder="1" FldMultithread="1" FldName="Account Creation Channel"> <ConsumersArray> <FldConsumerObj> "/r_account" </FldConsumerObj> <FldPushOpcode> 745 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/account" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="10" FldFamilyId="100" FldOrder="2" FldMultithread="1" FldName="Account Modification Channel"> <ConsumersArray> <FldConsumerObj> "/r_account" </FldConsumerObj> <FldPushOpcode> 745 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/event/customer/nameinfo" </FldSupplierObj> <FldSupplierObj> "/event/customer/product_status" </FldSupplierObj> <FldSupplierObj> "/event/customer/status" </FldSupplierObj> <FldSupplierObj> "/event/customer/billinfo"</FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="20" FldFamilyId="100" FldOrder="3" FldMultithread="0" FldName="Service Creation Channel"> <ConsumersArray> <FldConsumerObj> "/r_service" </FldConsumerObj> <FldPushOpcode> 745 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/service" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="40" FldFamilyId="100" FldOrder="4" FldMultithread="1" FldName="Service Modification Channel"> <ConsumersArray> <FldConsumerObj> "/r_service" </FldConsumerObj> <FldPushOpcode> 745 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/event/customer/login" </FldSupplierObj> <FldSupplierObj> "/event/customer/password" </FldSupplierObj> <FldSupplierObj> "/event/notification/service" </FldSupplierObj> <FldSupplierObj> "/event/customer/status" </FldSupplierObj> <FldSupplierObj> "/event/billing/product" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="50" FldFamilyId="200" FldOrder="1" FldMultithread="1" FldName="Account Creation Channel"> <ConsumersArray> <FldConsumerObj> "/r_account" </FldConsumerObj> <FldPushOpcode> 746 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/account" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="70" FldFamilyId="200" FldOrder="2" FldMultithread="0" FldName="Account Modification Channel"> <ConsumersArray> <FldConsumerObj> "/r_account" </FldConsumerObj> <FldPushOpcode> 746 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/event/customer/nameinfo" </FldSupplierObj> <FldSupplierObj> "/event/customer/status" </FldSupplierObj> <FldSupplierObj> "/event/customer/billinfo" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="60" FldFamilyId="200" FldOrder="3" FldMultithread="1" FldName="Broadband Creation Channel"> <ConsumersArray> <FldConsumerObj> "/r_service" </FldConsumerObj> <FldPushOpcode> 746 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/service/broadband" </FldSupplierObj> </SuppliersArray> </Channel> <Channel FldChannelId="80" FldFamilyId="200" FldOrder="4" FldMultithread="1" FldName="Broadband Usage Channel"> <ConsumersArray> <FldConsumerObj> "/r_service" </FldConsumerObj> <FldPushOpcode> 746 </FldPushOpcode> </ConsumersArray> <SuppliersArray> <FldSupplierObj> "/event/broadband" </FldSupplierObj> <FldSupplierObj> "/event/broadband/usage" </FldSupplierObj> </SuppliersArray> </Channel> </ChannelConfig>
The "pin_channel_export" utility publishes channel events to an LDAP database according to their channel ID (PIN_FLD_POID) and family ID (PIN_FLD_FAMILY_ID), if specified.
Note:
You must have one instance of the pin_channel_export utility running for each family ID in your system.Each pin_channel_export instance does the following:
If specified, uses the family ID value in the -f parameter to retrieve a batch of channels with that family ID. The channels are retrieved in increasing order of the channel IDs.
Reads the channel configurations that were retrieved and processes channel events by:
Prioritizing the channels based on the PIN_FLD_CHANNEL_ORDER value.
Determining whether channels should be published serially or in parallel based on the PIN_FLD_MULTI_THREADED value.
Reading the PIN_FLD_CONSUMER_OBJ value to determine which LDAP DM to send the results to.
Calls the PCM_OP_REPL_POL_PUSH policy opcode to publish the channel events to respective LDAP databases.
After the "pin_channel_export" utility has cycled through all necessary channels, it sleeps for the period specified in its pin.conf file and then starts the publishing cycle again.
For information on the channel configuration values, see "About Defining Channels".
You can define any number of LDAP directory servers to which you publish data. Before publishing data, make certain you:
Configure the CM pin.conf file, including the following entries:
Set the -ldap_db entry for each LDAP database in your system.
Set the -dm_pointer entry for each LDAP DM in your system.
Configure each /channel object to contain the LDAP database number in the PIN_FLD_CONSUMER_OBJ field. The PCM_OP_REPL_POL_PUSH policy opcode retrieves this value when publishing data. See "Configuring Channel Definitions".
Set up one instance of the pin_channel_export utility for each family ID in your system and make sure they both point to the same CM.
For example, Figure 2-9 shows two instances of the pin_channel_export utility (one for family 100 and one for family 200) which publish channels to the BRM database and two LDAP databases. Each database is connected to its own DM:
Figure 2-9 Double pin_channel_export Instance Publishing
The channel IDs and channel family IDs must be unique across each LDAP database. This is a requirement for multidatabase publishing. For example, say you have the configuration described in Table 2-2 defined in your system:
Table 2-2 Example Channel ID and Family Configuration
Database | Family ID | Channel ID | Validity | Description |
---|---|---|---|---|
0.0.5.1 |
100 |
10, 20, 30, 40 |
Valid |
These are the first unique family ID and channel IDs defined in the system. |
Table 2-3 lists the scenarios that are either invalid or valid, depending on the database number, the family ID, and the channel IDs defined:
Database | Family ID | Channel ID | Validity | Description |
---|---|---|---|---|
0.0.6.1 |
200 |
50,60,70,80 |
Valid |
The family ID and channel IDs are unique across the databases. |
0.0.6.1 |
100 |
10,20,30,40 |
Invalid |
The family ID and channel IDs are already defined in database 0.0.5.1. |
0.0.6.1 |
100 |
50,60,70,80 |
Invalid |
The family ID is already defined in database 0.0.5.1. |
0.0.6.1 |
200 |
10,20,30,40 |
Invalid |
The channel IDs are already defined in database 0.0.5.1 |
This example shows how the family ID is used to publish channels to an LDAP database. Channel IDs 10, 20, 30, and 40 have a family ID value of 100. In addition, they all have the same PIN_FLD_CONSUMER_OBJ value of 0.0.5.1, which means they are all published to the same LDAP database.
When you run the pin_channel_export utility with the -f parameter value set to 100, the channels for that family ID are first prioritized by order, and, for each channel, the pin_channel_export utility does the following:
Searches for /channel_event objects in the BRM database.
Calls the PCM_OP_REPL_POL_PUSH policy opcode (defined in the PIN_FLD_PUSH_OPCODE field) to read the LDAP database number from the PIN_FLD_CONSUMER_OBJ field.
Reads the CM pin.conf file to determine the LDAP DM for the LDAP database retrieved.
Reads the channel's PIN_FLD_MULTI_THREADED value to determine whether to publish the channel events serially or in parallel.
The result is that all channel events for channel IDs 10, 20, 30, and 40 are pushed to LDAP DM 0.0.5.1 using three threads as shown in Figure 2-10:
Figure 2-10 Example of Publishing a Channel Family
Note:
To connect to the BRM database, the load_channel_config utility needs a configuration file in the directory from which you run the utility. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.When you set up replicatable objects as consumers, BRM uses the supplier/consumer/channel paradigm. BRM predefines several /channel configuration objects in the BRM_Home/sys/dd/data/init_objects.source file.
Each channel object contains two array fields:
Consumer array (PIN_FLD_CONSUMERS)
Supplier array (PIN_FLD_SUPPLIERS)
You can register a list of suppliers for a particular /channel object by adding new array elements to the PIN_FLD_SUPPLIERS array. The consumers for each of the /channel objects are the replicated objects that the replication module and the LDAP Manager Data Manager create.
The next sections describe the BRM LDAP channel configuration objects and the logical data that these objects track.
The /channel 100 channel object tracks new account creation.
The /channel 101 channel object tracks changes to /account objects. In particular, it tracks modifications to customer billing information, name information, and whether the product status is active or closed or whether a credit card is valid or invalid.
The /channel 102 object tracks changes to /service objects.
The /channel 103 object propagates changes to /service objects.
The channel framework uses the PCM_OP_REPL_POL_PUSH opcode to implement the push operation.
This opcode implements the translation logic for /account and /service storable objects.
This policy opcode performs one of the following mapping functions. The mapping function for PCM_OP_REPL_POL_PUSH is determined by the Connection Manager (CM) pin.conf user_scheme entry.
If user_scheme is 0, the opcode maps the /account and /service storable objects one-to-one to /r_account and /r_service objects respectively. There will be one entry in the directory for every object in BRM.
If user_scheme is 1, the opcode merges the /account and /service storable object fields to form the /r_user storable object.
By default, the Connection Manager user_scheme pin.conf entry is set to 1, and the LDAP Data Manager implements a single-entry mapping operation.
If the PIN_FLD_POID field in the input flist indicates that the consumer is /r_account -1, this opcode does the following operations:
If the supplier is /account -1, it searches for all accounts created within the time range passed to this opcode by the input fields PIN_FLD_INVOKE_T and PIN_FLD_LAST_INVOKE_T. For each account, it reads a subset of the account fields and forms a replicated object /r_user. It then invokes the PCM_OP_CREATE_OBJ operation on dm_ldap to create the directory entry, which serves as the replica of this /r_user object.
For all other suppliers, it searches for all events created within the time range. For the account associated with each event, it reads the same subset of the account fields from the previous step, and invokes the PCM_OP_WRITE_FLDS operation on dm_ldap to modify the directory entry.
If the PIN_FLD_POID field in the input flist indicates that the consumer is /r_service -1, this opcode does the following operations:
If the supplier is /service -1, it searches for all services created within the time range passed to this opcode by the input fields PIN_FLD_INVOKE_T and PIN_FLD_LAST_INVOKE_T. For each service, it reads a subset of the service fields and invokes the PCM_OP_WRITE_FLDS operation on dm_ldap, and modifies the directory entry that corresponds to the /r_user object. The modified directory entry relates to the /account object to which the service belongs.
For all other suppliers, this opcode searches for services modified within the time range. For each service, it reads the same subset of the service fields as in the previous step, and invokes the PCM_OP_WRITE_FLDS operation on dm_ldap to modify the directory entry.
The default implementation for push operations is as follows:
BRM searches for all events listed in the supplier list and retrieves a list of the changed /account objects (sources).
For each /account object, BRM calls PCM_OP_REPL_POL_PUSH operations with the corresponding replicatable object PID ID.
BRM sends the result of the push operation to the LDAP Data Manager based on the LDAP database specified in the PIN_FLD_CONSUMER_OBJ value and the family ID (PIN_FLD_FAMILY_ID), if specified. See "How Channel Events are Published".
The module that controls what BRM data gets pushed and how it is structured in the directory server is the replication module. BRM calls the replication module from the channel framework synchronization operation for each channel event object in the channel event table.
Figure 2-11 shows the replication module data flow:
Figure 2-11 Replication Module Data Flow
The replication module implements the translation logic for /account and /service objects, handling account and service creation and modification. By default, the replication module merges fields from /account and /service objects during the translation. For more information, see "Defining the User Mapping Scheme".
The replication policy, PCM_OP_REPL_POL_PUSH, pushes data about the object whose POID is supplied in the input flist. It locates the account supplied in the input flist and performs the operations shown in Figure 2-12:
Figure 2-12 Replication Policy Default Implementation
Reads a subset of the account fields, such as bill_type and currency.
LDAP Data Manager derives this information from the field list in the mapping file.
Forms the replicatable /r_user object (assuming user scheme).
Calls the create object opcode, PCM_OP_CREATE_OBJ on dm_ldap to create the directory entry, which serves as the replica of this /r_user object.
Iteratively reads the same subset of account fields for all other suppliers (assuming events) and calls the PCM_OP_WRITE_FLDS operation on dm_ldap to modify the directory entry.
The opcode searches for the object whose POID was supplied in the input flist. For that service, it reads a subset of the service fields and calls the PCM_OP_WRITE_FLDS operation on dm_ldap to modify the directory entry that corresponds to the /r_user object.
The user mapping scheme maps BRM /account and /service objects to one entry in the directory server, and it is deemed acceptable in a single-logon environment.
The parameter that controls whether BRM uses this scheme is the Connection Manager user_scheme entry in the Connection Manager (CM) pin.conf file. If the user_scheme is set to 1, the LDAP Data Manager uses the user mapping scheme.
Figure 2-13 shows how BRM maps the /account and /service objects to the ruser entry in the directory server:
Figure 2-13 /account and /service Object Mapping to ruser Entry
The replication policy uses fields from the /account and /service objects to form an /r_user object. The LDAP Data Manager uses the data in the /r_user object and pushes it to the directory server. The replication policy determines whether to use this merge /r_user object by reading the user_scheme entry of the CM pin.conf file.
For more information on the Connection Manager pin.conf file, see "Configuring the Connection Manager for LDAP Manager".
The /r_user object uses fields from the BRM /account and /service objects. You map attributes in the mapping file to BRM fields. Some of these attributes are predefined for LDAP directory servers; however, the BRM-specific attributes cannot be created automatically. For more information on defining the ruser object class in the directory server, "Determining the /r_user Object Class Attributes".
In the user scheme, it is possible for the field name spaces to collide. Fields such as the status field in /account and /service objects have different field and attribute names in the /r_user object (for example, PIN_FLD_ACCOUNT_STATUS and PIN_FLD_SERVICE_IP_STATUS).
Note:
With the user scheme, it is difficult for an account to have multiple services of a given type. BRM usually allows this.The following example shows a default mapping file for the LDAP Data Manager (ldap.idl) for the user scheme:
# Class Definitions: # All attributes need to be defined in the directory server # All the entry_type objectclasses and attrval objectclasses need to be # defined in the directory server. # STORABLE CLASS /r_user { POID PIN_FLD_POID { CREATE = System; MODIFY = System; } TIMESTAMP PIN_FLD_CREATED_T { CREATE = System; MODIFY = System; } TIMESTAMP PIN_FLD_MOD_T { CREATE = System; MODIFY = System; } STRING PIN_FLD_NAME { CREATE = Optional; MODIFY = Writeable; } POID PIN_FLD_ACCOUNT_OBJ { CREATE = Required; MODIFY = Writeable; } STRING PIN_FLD_ACCOUNT_NO { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_FIRST_NAME { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_LAST_NAME { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_ACCOUNT_STATUS { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_BILL_TYPE_NAME { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_ADDRESS { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_CURRENCY_NAME { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_LOGIN { CREATE = Required; MODIFY = Writeable; } STRING PIN_FLD_PASSWD { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_EMAIL_LOGIN { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_EMAIL_STATUS { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_IP_LOGIN { CREATE = Optional; MODIFY = Writeable; } STRING PIN_FLD_IP_STATUS { CREATE = Optional; MODIFY = Writeable; } INT PIN_FLD_MAX_MBOX_SIZE { CREATE = Optional; MODIFY = Writeable; } INT PIN_FLD_MAX_MSG_CNT { CREATE = Optional; MODIFY = Writeable; } INT PIN_FLD_MAX_MSG_SIZE { CREATE = Optional; MODIFY = Writeable; } ARRAY PIN_FLD_ARGS { STRING PIN_FLD_ARG { CREATE = Optional; MODIFY = Writeable; } } } STORABLE CLASS /r_user IMPLEMENTATION LDAPV3 { ATTRVAL = "objectClass : top"; ATTRVAL = "objectClass : person"; ATTRVAL = "objectClass : inetOrgPerson"; ENTRY_TYPE = "ruser"; LOCATION = "o=portal.com"; POID PIN_FLD_POID { ATTRIBUTE = "pinpoid"; } TIMESTAMP PIN_FLD_CREATED_T { ATTRIBUTE = "pincreatedt"; } TIMESTAMP PIN_FLD_MOD_T { ATTRIBUTE = "pinmodt"; } STRING PIN_FLD_NAME { ATTRIBUTE = "cn"; } POID PIN_FLD_ACCOUNT_OBJ { ATTRIBUTE = "billingid"; } STRING PIN_FLD_ACCOUNT_NO { ATTRIBUTE = "accountno"; } STRING PIN_FLD_FIRST_NAME { ATTRIBUTE = "givenname"; } STRING PIN_FLD_LAST_NAME { ATTRIBUTE = "sn"; } STRING PIN_FLD_ACCOUNT_STATUS { ATTRIBUTE = "billingstatus"; } STRING PIN_FLD_BILL_TYPE_NAME { ATTRIBUTE = "billingtype"; } STRING PIN_FLD_ADDRESS { ATTRIBUTE = "billingaddress"; } STRING PIN_FLD_CURRENCY_NAME { ATTRIBUTE = "currency"; } STRING PIN_FLD_LOGIN { ATTRIBUTE = "uid"; RDN_PIECE = 1; } STRING PIN_FLD_PASSWD { ATTRIBUTE = "userpassword"; } STRING PIN_FLD_EMAIL_LOGIN { ATTRIBUTE = "mail"; } STRING PIN_FLD_EMAIL_STATUS { ATTRIBUTE = "mailstatus"; } STRING PIN_FLD_IP_LOGIN { ATTRIBUTE = "iplogin"; } STRING PIN_FLD_IP_STATUS { ATTRIBUTE = "ipstatus"; } INT PIN_FLD_MAX_MBOX_SIZE { ATTRIBUTE = "mailquota"; } INT PIN_FLD_MAX_MSG_CNT { ATTRIBUTE = "mailmaxmsgcount"; } INT PIN_FLD_MAX_MSG_SIZE { ATTRIBUTE = "mailmaxmsgsize"; } ARRAY PIN_FLD_ARGS { STRING PIN_FLD_ARG { ATTRIBUTE = "ipargs"; MULTIVALUED = 1; } } }
Table 2-8 summarizes the opcodes that capture changes made to /account and /service objects (so that fields in these objects can then be pushed to the directory server:
Table 2-8 Related /account and /service Opcodes
Opcode(s) | Action |
---|---|
PCM_OP_CUST_COMMIT_CUSTOMER PCM_OP_CUST_PREP_CUSTOMER |
Accepts the DNs for the /account storable object in the form of an optional /profile/ldap storable object. |
PCM_OP_ACT_POL_EVENT_NOTIFY |
Calls CM_OP_CHANNEL_PUSH to create an entry in the channel_event table to track changes. |
PCM_OP_CUST_POL_ENCRYPT_PASSWD |
Disables or enables encryption of the /service/ldap password. |
PCM_OP_CUST_CREATE_ACCT |
Calls PCM_OP_CHANNEL_PUSH to create an entry in the channel_event table to track creation of accounts. |
PCM_OP_CUST_CREATE_SERVICE |
Calls PCM_OP_CHANNEL_PUSH to create an entry in the channel_event table to track creation of services. |
PCM_OP_TRANS_POL_COMMIT |
Defers PCM_OP_CHANNEL_SYNC automatically. |
BRM cannot automatically create directory server entries. Therefore, you must manually define the BRM data elements that you are interested in capturing with your own directory server tools.
For example, BRM-specific information such as the POID must map to a pinpoid attribute, which is not predefined the directory server. For this reason, you must create a replicatable user object for BRM to use in the directory server. BRM can then modify the schema of a particular entry based on how it is configured.
The next table describes the BRM /r_user object and how it is composed of BRM fields in the /service and /account objects as well as its corresponding directory attributes, and whether they are predefined in the LDAP directory server.
Refer to Table 2-9 when you create the ruser directory server entry and its corresponding BRM attributes for replication purposes. This table also lists the fields that BRM pushes to the directory server by default.
Important:
Case is significant for the directory server attributes. For example, you must enter givenName, not givenname. If you do not enter these attributes exactly as shown, you will encounter object class violations when you map BRM fields to directory server attributes.
Make sure that the object class name in the directory server matches the entry type name in the ldap.idl mapping file.
Table 2-9 Default Directory Server Fields
/r_user Field | Object Components and Comments | Directory Attribute | Predefined in LDAP |
---|---|---|---|
PIN_FLD_POID |
/account. ldap_db db_no + POID ID |
pinpoid |
N |
PIN_FLD_CREATED_T |
Created time set by dm_ldap |
pincreatedt |
N |
PIN_MOD_T |
Modified time set by dm_ldap |
pinmodt |
N |
PIN_FLD_NAME |
/account. Composed by concatenating the first_name, middle_name, and last_name fields. PIN_FLD_BILLINFO [PIN_NAMEINFO_BILLING] |
cn - LDAP |
Y |
PIN_FLD_ACCOUNT_OBJ |
/account.PIN_FLD_POID |
billingid |
N |
PIN_FLD_ACCOUNT_NO |
/account.PIN_FLD_ACCOUNT_NO |
accountno |
N |
PIN_FLD_FIRST_NAME |
See PIN_FLD_NAME |
givenName |
Y |
PIN_FLD_LAST_NAME |
See PIN_FLD_NAME |
sn |
Y |
PIN_FLD_ACCOUNT_STATUS |
/account.PIN_FLD_STATUS Values: Active, Inactive, and Closed |
billingstatus |
N |
PIN_FLD_BILL_TYPE_NAME |
/account.PIN_FLD_BILL_TYPE Values: Prepaid, Invoice, Debit, Credit Card, Direct Debit, Smart Card, Subordinate, Internal, Guest, Cash, Check, Wire Transfer, Inter-Bank Payment Order, Postal Order, Unknown |
billingtype |
N |
PIN_FLD_ADDRESS |
/account.PIN_FLD_NAMEINFO[PIN_NAMEINFO_BILLING]: Street, city, state, ZIP code, and country concatenated using comma separators |
billingaddress |
N |
PIN_FLD_CURRENCY_NAME |
/account.PIN_FLD_CURRENCY. (String BEID name such as US Dollar from /config/beid_balances) |
currency |
Y |
PIN_FLD_LOGIN |
Login associated with /service/ldap for LDAP Manager |
uid [RDN component] for LDAP Manager |
Y |
PIN_FLD_PASSWD |
Cleartext password associated with /service/ldap for LDAP Manager |
userPassword |
Y |
PIN_FLD_EMAIL_LOGIN |
/service/email. Login |
|
Y |
PIN_FLD_EMAIL_STATUS |
/service/email. PIN_FLD_STATUS Values: Active, Inactive, and Closed |
mailstatus |
N |
PIN_FLD_IP_LOGIN |
/service/ip. Login |
iplugin |
Y |
PIN_FLD_IP_STATUS |
/service/ip.PIN_FLD_STATUS Values: Active, Inactive, and Closed |
ipstatus |
N |
PIN_FLD_MAX_MBOX_SIZE |
/service/email.PIN_FLD_SERVICE_EMAIL.PIN_FLD_MAX_MBOX_SIZE |
mailboxQuota |
Y |
PIN_FLD_MAX_MSG_CNT |
/service/email.PIN_FLD_SERVICE_EMAIL PIN_FLD_MAX_MSG_CNT |
mailmaxmsgcnt |
N |
PIN_FLD_MAX_MSG_SIZE |
/service/emailad |
mailmaxmsgsize |
N |
PIN_FLD_PATH |
/service/email.PIN_FLD_SERVICE_EMAIL.PIN_FLD_PATH |
mailmessagestore |
Y |
PIN_FLD_ARGS[].PIN_FLD_ARG |
/service/ip.PIN_FLD_ARGS. The PIN_FLD_NAME and PIN_FLD_VALUE are concatenated (using "=" separators) |
ipargs |
N |
To replicate data from BRM to your directory server, you must set up the ruser object class in your directory server:
Start your LDAP directory server.
Define the ruser object class in the LDAP directory server or Membership directory.
Use the /r_user mapping table described in the previous section to define the required BRM-specific attributes that you want to replicate to the list of allowable attributes in the ruser objectClass.
Save the object class in the directory server.
Change the value of the LOCATION key in the implementation section of the /r_user object definition in the ldap.idl mapping file.
The one-to-one mapping scheme maps one BRM object to one LDAP directory entry. Figure 2-14 shows how BRM maps the /account and /service objects to the raccount and rservice entries in the directory server.
Figure 2-14 BRM /raccount and rservice Object Mapping in Directory Server
To use the one-to-one mapping scheme, you must modify the replication policy C source code file. After you define the LDAP schema, you modify the replication policy (PCM_OP_REPL_POL_PUSH) to perform multiple pushes; one for the account and one for each service.
Note:
The default implementation for the one-to-one mapping scheme in the replication module exports only /service/email and /service/ip objects.To use the one-to-one mapping scheme:
Set the user_scheme entry of the Connection Manager (CM) pin.conf file to 0. See "Configuring the Connection Manager for LDAP Manager".
Map the following classes in the LDAP Data Manager mapping file (ldap.idl). You can find the mapping file in BRM_Home/sys/dm_ldap.
/r_account
/r_service
/r_service/ip
/r_service/email
See "One-to-One Mapping File Example" for the details.
Tip:
You can define the mappings in a new file and point to it from the LDAP Data Manager pin.conf file.Define raccount and rservice object classes in the directory server.
For each of the /r_account and /r_service, /r_service/ip and /r_service/email fields you want to export, define a corresponding attribute and add to the list of allowed attributes of the raccount or rservice object classes.
Set up the rservice object class to allow all attributes mapped to /r_service and its subtypes (/r_service/email and /r_service/ip).
Note:
The LDAP Data Manager mapping scheme requires you to map to one ENTRY_TYPE per class and its subtypes.Modify the replication policy C source code file, fm_repl_pol_translate.c.
This file implements the replication policy PCM_OP_REPL_POL_PUSH. See "Changing the Replication Policy for the One-to-One Mapping Scheme" for details.
This example shows a subset of the mapping file (the implementation section) as an example for the one-to-one mapping scheme.
## ## /r_account (to represent Portal /account storable class) ## STORABLE CLASS /r_account { # list all the /r_account fields (similar to the /r_user fields in the user scheme # without the service related fields like PIN_FLD_EMAIL_LOGIN, etc. #PIN_FLD_POID #PIN_FLD_CREATED_T #PIN_FLD_MOD_T #PIN_FLD_NAME #PIN_FLD_ACCOUNT_OBJ #PIN_FLD_ACCOUNT_NO #PIN_FLD_FIRST_NAME #PIN_FLD_LAST_NAME #PIN_FLD_ACCOUNT_STATUS #PIN_FLD_BILL_TYPE_NAME #PIN_FLD_ADDRESS #PIN_FLD_CURRENCY_NAME #PIN_FLD_GUID #PIN_FLD_LOGIN #PIN_FLD_PASSWD } # STORABLE CLASS /r_account IMPLEMENTATION LDAPV3 { # ENTRY_TYPE = "raccount"; # LOCATION = "o=xyz, c=US"; # provide mapping for /r_account fields } ## ## /r_service (to represent Portal /service storable class) ## STORABLE CLASS /r_service { # list all the /r_service fields # PIN_FLD_POID # PIN_FLD_CREATED_T # PIN_FLD_MOD_T # PIN_FLD_ACCOUNT_OBJ # PIN_FLD_LOGIN # PIN_FLD_PASSWD # PIN_FLD_STATUS } ## /r_service/ip (to represent Portal /service/ip storable class) STORABLE CLASS /r_service/ip { # list all the /r_service/ip related fields # PIN_FLD_ARGS #PIN_FLD_ARG } ## /r_service/email (to represent Portal /service/email storable class) STORABLE CLASS /r_service/email { # list all the /r_service/email related fields # PIN_FLD_EMAIL_INFO #PIN_FLD_MBOX_SIZE #PIN_FLD_MAX_MSG_CNT #PIN_FLD_MAX_MSG_SIZE } # STORABLE CLASS /r_service IMPLEMENTATION LDAPV3 { # ENTRY_TYPE = "rservice"; # LOCATION = "ou=services, o=xyz, c=US"; # provide mapping for /r_service fields # MAKE PIN_FLD_POID as the RDN_PIECE. } # STORABLE CLASS /r_service/ip IMPLEMENTATION LDAPV3 { # provide mapping for /r_service/ip fields } # STORABLE CLASS /r_service/email IMPLEMENTATION LDAPV3 { # provide mapping for /r_service/email fields }
Use this section to guide you in modifying the PCM_OP_REPL_POL_PUSH replication policy. You make all changes to the C source code file fm_repl_pol_translate.c, which is located at:
BRM_Home/source/sys/fm_repl_pol
Save a copy of fm_repl_pol_translate.c.
Package the input flist to LDAP Data Manager to match the mapping information you specified in the mapping file (ldap.idl) file associated with dm_ldap as described in "LDAP Data Manager Mapping Files".
In the fm_repl_pol_prep_service_flds() function, drop the PIN_FLD_STATUS and PIN_FLD_LOGIN associated with /service/ldap only if you are using the user_scheme.
In the fm_repl_pol_prep_service_email_flds() function, move the information in the PIN_FLD_SERVICE_EMAIL substruct to the PIN_FLD_EMAIL_INFO array field as shown here:
e_flistp = PIN_FLIST_SUBSTR_TAKE(rep_flistp, PIN_FLD_SERVICE_EMAIL, 0, ebufp); if (user_scheme) { PIN_FLIST_CONCAT(rep_flistp, e_flistp, ebufp); PIN_FLIST_DESTROY(e_flistp, NULL); } else { PIN_FLIST_ELEM_PUT(rep_flistp, e_flistp, PIN_FLD_EMAIL_INFO, 0, ebufp); }