3 Managing the Directory Server Organization

This chapter describes how to use the Oracle Communications Billing and Revenue Management (BRM) LDAP API to manage and manipulate the directory tree organization.

About Managing Directory Server Entries

You can create, delete, read, and write directory server entries and attributes in any part of a directory tree.

BRM uses Distinguished Names (DNs) for these operations in one of two ways:

  • From the location value in the mapping file

  • From the location in the input flist based on:

    • The location value and Relative Distinguished Name (RDN) piece

    • The DN field and DN qualifiers (complete and prefixed) used in the create operation. The create operation can also use the parent DN qualifier.

For more information, see "Specifying Directory Tree Entries".

The BRM LDAP Data Manager makes the following assumptions during create, delete, read, and write operations with the DN you supply at run time:

  • The directory server entry is an instance of the object defined in the mapping file.

  • The location value matches the location you specified in the mapping file.

Semantics for the LDAP Modify Operation

You use the LDAP modify operation to manage directory server entries. This operation is used by the following opcodes:

  • PCM_OP_DELETE_FLDS

  • PCM_OP_DELETE_OBJ

  • PCM_OP_WRITE_FLDS

  • PCM_OP_CREATE_OBJ

The LDAP modify operation accepts a list of modifications to be performed, and performs the modifications in the order listed as a single atomic operation. The value that may be taken on by the operation field in each modification construct can have the following semantics:

  • Add: Adds specified values to the given attribute and creates the attribute if necessary.

  • Delete: Deletes specified values from the given attribute. Removes the entire attribute if no values are specified or if all existing values of the attribute are listed for deletion.

  • Replace: Replaces all existing values of the given attribute with the specified values, and creates the attribute if it does not already exist. Using replace with no specified values deletes the entire attribute.

Distinguished Name Field and the DN Flags Field

Use the Distinguished Name field, PIN_FLD_DN, and the Distinguished Name flags field, PIN_FLD_DN_FLAGS with one of its values to specify the locations in the directory tree shown in Table 3-1:

Table 3-1 PIN_FLD_DN Settings

Value Meaning

0

Complete DN.

To specify a complete DN, pass the complete DN of the entry in the PIN_FLD_DN field. You can optionally set PIN_FLD_DN_FLAGS to 0.

For more detailed information and an example, see "Using a Complete Distinguished Name".

1

Prefixed DN.

To specify a prefixed DN, pass the prefixed DN of the entry in the PIN_FLD_DN field and set the PIN_FLD_DN_FLAGS to 1.

A prefixed DN is the case when the module that calls the LDAP Data Manager (typically, PCM_OP_REPL_POL_PUSH) passes in the RDN as a prefix.

For more detailed information and an example, see "Using a Prefixed Distinguished Name".

2

Parent DN.

You cannot use the parent value as a flag to the following opcodes:

  • PCM_OP_DELETE_FLDS

  • PCM_OP_DELETE_OBJ

  • PCM_OP_WRITE_FLDS

You can only use the parent value with PCM_OP_CREATE_OBJ.

To specify a parent DN, pass the parent DN of the entry in the PIN_FLD_DN field, and set the PIN_FLD_DN_FLAGS to 2.

For more detailed information and an example, see "Using a Parent Distinguished Name (Create Operation Only)".

The Location Field

You can use the location field, PIN_FLD_LOCATION to override the base LOCATION value specified in the mapping file. The override is a one shot override for that particular operation only. This lets you specify a different tree root location (base DN) for the directory server entry. For more detailed information and an example, see "Overriding the Base DN Location".

Creating Directory Server Entries

This section describes the default control logic of the LDAP create operation.

For information on specifying directory tree entries, see "Specifying Directory Tree Entries".

To create new directory server entries or reuse entries in the directory server for replication purposes, use the LDAP PCM_OP_CREATE_OBJ base opcode.

The LDAP PCM_OP_CREATE_OBJ base opcode performs the following operations:

  • Makes entries compatible with BRM by adding these BRM fields:

    • Portal object ID (POID)

    • PIN_FLD_POID

    • CREATED_T

    • MOD_T

  • Composes the Distinguished Name (DN).

  • Accepts the Distinguished Name (DN) of the entry as an input.

PCM_OP_CREATE_OBJ requires the following inputs:

  • PIN_FLD_POID. Use the replica POID for this field.

  • PCM_OP_USE_POID_GIVEN opflag.

  • Other fields depending on the object you create.

    Note:

    When writing array elements, this opcode does not use the element ID.

If you specify a Distinguished Name for the PIN_FLD_DN field in the input flist, the LDAP Data Manager creates a directory entry with the DN that you provide. If the entry already exists, this opcode ignores the error and performs a modify directory operation instead of an add directory operation.

Note:

The modify directory operation updates all attributes in an entry.

For more information see "Semantics for the LDAP Modify Operation".

Distinguished Name Control Logic for PCM_OP_CREATE_OBJ

You can specify the location in the directory tree by using the PIN_FLD_DN, PIN_FLD_DN_FLAGS as well as the PIN_FLD_LOCATION fields:

  • If you use the PIN_FLD_DN in the input flist, the create opcode creates an entry with the value of the DN you provide.

  • If you do not supply a DN for the PIN_FLD_DN field, the LDAP Data Manager uses the RDN_PIECE in the mapping file to compose the Relative Distinguished Name (RDN).

  • If you use the PIN_FLD_DN field without the PIN_FLD_DN_FLAGS in the input flist, then the create opcode assumes you want to pass in a complete DN. This sets the PIN_FLD_DN_FLAGS field to 0.

  • If you use the PIN_FLD_DN field with the PIN_FLD_DN_FLAGS field set to 1, then the create opcode appends the LOCATION value to construct the DN. This is the prefixed DN.

  • If you use the PIN_FLD_DN field with the PIN_FLD_DN_FLAGS field set to 2, then the create opcode appends the LOCATION to PIN_FLD_DN. It then appends this to the value specified for the attribute that is tagged as the RDN_PIECE in the mapping file. This is the parent DN case.

    Note:

    You can specify only a parent DN for the create opcode.

If you use the PIN_FLD_LOCATION field in the input flist, the create opcode overrides the location value that you specified in the mapping file for this operation. If you do not use this field in the input flist, the create opcode assumes that you want to use the location value you specified in the mapping file.

Pre-Existing Distinguished Names

If you supply a DN in the input flist for PCM_OP_CREATE_OBJ, and an entry with the same DN exists in the directory server, BRM adds the information to the existing entry based on the information that you provide.

LDAP Data Manager does not treat pre-existing entries as errors.

Supplying Distinguished Names

If you supply a DN to the LDAP Data Manager for the PCM_OP_CREATE_OBJ operation, BRM uses it to create a directory server entry. This lets you use existing LDAP customer entries and also gives you flexibility in assigning DNs.

Not Supplying Distinguished Names

If you do not supply a DN to the LDAP Data Manager for the PCM_OP_CREATE_OBJ operation, BRM uses the attribute tagged with the key RDN_PIECE in the mapping file as the RDN.

For example, the LOCATION "o=portal.com" is appended to the value specified for the attribute cn (tagged as RDN_PIECE) in the mapping file to compose the REAL DN, "cn=john,o=portal.com".

Understanding Matching Rules for Distinguished Names

You control the location of directory tree entries by using a combination of values in the mapping file and by using DN qualifiers, or location parameters at run time as inputs to the BRM LDAP create, delete, read, and write operations.

LDAP Data Manager uses static and dynamic matching rules for DNs to determine the location for directory server entries in the directory tree.

Using Static Controls for DNs

The LDAP Data Manager lets you specify the location of directory server entries statically for each object type by using the LOCATION key in the mapping file. You specify different LOCATION values for different object types as follows:

STORABLE CLASS /info1 IMPLEMENTATION LDAPV3 {
LOCATION = "ou=portal,c=US";
}
STORABLE CLASS /info2 IMPLEMENTATION LDAPV3 {
LOCATION = "ou=abc,o=xyz,c=US";
}

Using Dynamic Controls for DNs

LDAP Data Manager lets you manipulate the static controls in the mapping file by using the control field for DNs, the PIN_FLD_DN field and a flag for the DN, PIN_FLD_FLAGS.

Rule matching for the given DN with the LOCATION field allows entries to be at arbitrary depths relative to the location instead of limiting entries to one location. For example:

If

LOCATION = "o=portal.com"

Then the following locations are accepted:

PIN_FLD_DN = "cn=john, ou=dev, ou=engg, o=portal.com"

Deleting Directory Server Entries

To delete directory server entries, use the LDAP PCM_OP_DELETE_OBJ base opcode to perform the delete object operation. This opcode invokes the delete entry semantics of the LDAP modify operation in the directory server

To delete an entry from an existing directory server, create the PCM_OP_DELETE_OBJ input flist. Specify the complete POID or the DN of the entry in the flist.

PCM_OP_DELETE_OBJ performs the following operations:

  • Invokes the delete entry semantics of the LDAP modify operation in the directory server.

  • If the pinpoid attribute does not form the Relative Distinguished Name (RDN), this opcode locates the directory server entry first using a search operation and then deletes the object.

You must supply the PIN_FLD_POID (replica POID ID) and the POID of the object that you want to delete in the input flist.

For more information see "Semantics for the LDAP Modify Operation".

Changing Directory Server Entries

You can manage changes to directory server entries by performing the following operations:

The next sections describe how to accomplish these tasks.

For information on specifying directory tree entries, see "Specifying Directory Tree Entries".

Adding Attributes to an Existing Directory Server Entry

You can add an attribute that already exists in the directory server schema to an instance of an object defined in the mapping file. This lets you access and modify the schema of the directory server entry by using the BRM API.

Follow these rules when you add an attribute to the directory server:

  • If an attribute belongs to an auxiliary class, specify the attribute's auxiliary class in the mapping file.

  • An attribute can belong to only one auxiliary class.

  • Attribute names must be unique across object classes.

  • Attributes being added must already exist in the directory schema.

If you add an attribute that belongs to an auxiliary class to an existing directory server entry, the auxiliary class is automatically added to the entry.

To update or rename an entry, use the LDAP PCM_OP_WRITE_FLDS base opcode.

This opcodes performs the following operations:

  • Updates attributes by using the LDAP modify operation

  • Uses the replace semantics of the LDAP modify operation

  • Renames directory server entries

When you specify an array field, the entire array is replaced. The PCM_OPFLG_ADD_ENTRY opflag is used to invoke the add semantics, thereby adding new values to an existing entry.

You must supply the PIN_FLD_POID (replica POID ID) and at least one field that you want to write in the input flist. For rename operations, you can only specify the RDN piece as it is specified in the mapping file. You must also set the deleteOldRdn entry in the LDAP Data Manager pin.conf file to 1.

For more information see "Semantics for the LDAP Modify Operation".

For the procedure on renaming a directory server entries, see "Renaming Directory Server Entries".

To add an attribute to an existing directory server entry:

  1. Create the PCM_OP_WRITE_FLDS input flist:

    1. Add the complete POID or DN of the entry.

      If you specify the DN, make sure that the POID is a type-only POID, for example, POID [0] 0.0.5.1 /r_user -1.

    2. (Optional) Specify whether the DN is a complete or prefixed DN.

      By default, the write fields operation expects a complete DN. You can optionally supply a prefixed DN.

    To set up a complete DN, see "Using a Complete Distinguished Name".

    To set up a prefixed DN, see "Using a Prefixed Distinguished Name".

  2. In the mapping file, define all possible attributes including the auxiliary class that the directory server entry might contain.

  3. For the attribute you are adding:

    1. Set the CREATE string to Optional.

    2. Specify the auxiliary class that the attribute belongs to.

    In this sample, PIN_FLD_HTTP_URL corresponds to the attribute labeleduri for an auxiliary class called labeleduriobject.

    STORABLE CLASS /r_user {
...
STRING PIN_FLD_HTTP_URL {
CREATE = Optional;
MODIFY = Writeable;
}
STRING PIN_FLD_TYPE_STR {
CREATE = Optional;
MODIFY = Writeable;
}
...
}
STORABLE CLASS /r_user IMPLEMENTATION LDAPV3 {
...
STRING PIN_FLD_HTTP_URL {
ATTRIBUTE = "labeleduri";
OBJECTCLASS = "labeleduriobject";
}
STRING PIN_FLD_TYPE_STR {
ATTRIBUTE = "memberurl";
OBJECTCLASS = "mylabeleduriobject";
}
.......
}

Deleting Attributes from an Existing Directory Server Entry

To delete an attribute from an existing directory server entry, follow these rules:

  • Delete only those attributes that you have defined in the mapping file and are tagged as optional.

  • Do not delete fields that you have used for the RDN or any fields tagged as required. You can delete an entire array by using PIN_ELEM_ID_ANY.

    Important:

    Before you delete an attribute, make sure that doing so does not violate the schema constraints of the directory server entry. If you attempt to violate schema constraints, the LDAP Data Manager reports an object violation error.

For more information see "Semantics for the LDAP Modify Operation".

To delete values and attributes in an entry, use the LDAP PCM_OP_DELETE_FLDS base opcode. This opcode performs the delete operation by using the LDAP modify operation, which imposes delete semantics.

To delete an attribute from an existing directory server entry, create the PCM_OP_DELETE_FLDS input flist.

  1. Specify the complete POID or DN of the entry.

    You must supply the PIN_FLD_POID (replica POID) and at least one field that you want to delete in the input flist.

    If you specify the DN, make sure that the POID is a type-only POID, for example:

    POID [0] 0.0.5.1 /r_user -1

  2. (Optional) Specify whether the DN is a complete or prefixed DN.

  3. By default, the delete fields operation expects you to supply a complete DN. You can optionally supply a prefixed DN.

  4. Provide the names of the fields that you want to delete.

    0 PIN_FLD_<field to be deleted>
...
...

    The LDAP Data Manager deletes the attribute and the auxiliary object class if it is the last attribute belonging to that auxiliary class.

Renaming Directory Server Entries

You can rename a directory server entry in BRM. This is useful when the customer names or login names (RDN piece) of the directory server entry changes. For example, you can rename an entry for Jane Doe by changing her name to Jane Smith. In this case, this directory entry:

cn=Jane Doe; o=portal.com; c=US

Changes to this directory entry:

cn=Jane Smith; o=portal.com; c=US

Follow these rules when to rename directory server entries:

  • Do not rename the entry such that it moves to a different part of the directory tree.

  • Do not specify any field other than the field tagged by the RDN_PIECE in the mapping file in the input flist on this operation.

  • Rename only the left-most value in the DN entry. In the example above, this is the cn value.

    Important:

    When you use the write fields operation to rename entries, the input flist should not contain other fields.

LDAP Data Manager uses the PCM_OP_WRITE_FLDS opcode to rename entries. For more information on the inputs and outputs of this opcode, see PCM_OP_WRITE_FLDS. Additionally, it uses an entry in the LDAP Data Manager configuration file BRM_Home/sys/dm_ldap/pin.conf to determine if the old RDN value should be removed from the entry.

For more information see "Semantics for the LDAP Modify Operation".

To propagate a name change from BRM to the directory server entry:

  1. Create the PCM_OP_WRITE_FLDS input flist by adding the POID or complete DN of the old entry and the new name of the entry:

    0 PIN_FLD_POID POID [0]
0.0.5.1 /r_user <account_number>
0 PIN_FLD_LOGIN STR [0] "Jane Smith"

  2. In the pin.conf file, uncomment the following entry and set the delete value to 1.

    - ldap_ds deleteOldRdn 1

    Note:

    When you set the delete value to 1, LDAP Data Manager deletes the old RDN (Jane Doe). To keep the old RDN, set the delete value to 0.

    BRM reads the new value of the attribute tagged as the RDN_PIECE in the mapping file from the input flist and uses it to rename the entry.

Creating Subclass Objects in the Directory Server

You can extend, or subclass, an existing object class to add attributes to it. In this case, you use the create opcode to create subclass objects in any location in the directory server. You can create entries for a given BRM subclass object type in a particular part of the directory information tree independent of the location of objects belonging to the parent class. For example, /service objects can be located in the following location:

ou=Services, o=portal.com, c=US

The /service/email subclass object can be located in a different location:

ou=ServiceEmail, o=portal.com, c=US

To create a subclass object in the directory server independent of its parent's location:

  1. Using your directory server tools, create the organizational unit (ou) for the subclass object in the directory server.

  2. Create the corresponding subclass mapping for this attribute by specifying the LOCATION key in the implementation definition section of the mapping file.

  3. Start LDAP Data Manager and make sure that the dm_ldap.pinlog file reports no errors.

  4. Create the input flist that contains the complete POID or DN of the object that you want to create.

Creating Related Entries Under One Node

You can group any set of related entries under one node in the directory tree. To set up your BRM LDAP environment to replicate data in this type of structure, you use the link object attribute to define the related node entries in the mapping file.

For example, you can create all services associated with a particular account under the account entry in the directory tree.

If the creation of linked objects requires containers, this feature will not create the container objects automatically. You must create the containers for these objects with your directory server tools manually, as Figure 3-1 shows:

Figure 3-1 Manually Created Containers Example

Description of Figure 3-1 follows
Description of ''Figure 3-1 Manually Created Containers Example''

In each top-level service, you must use a link attribute that has the POID of the account that the service is linked to.

To group all services under an account:

Note:

This procedure assumes that your related services are linked.

  1. In the mapping file, configure the link object for each class and link attribute for each top-level class as in this example:

    Note:

    The link attribute must be a POID. Specify the types and link attributes for all classes.
    STORABLE CLASS /r_user {
...
}
##
## /r_service (to represent Portal /service storable class)
##
STORABLE CLASS /r_service {
# list all the /r_service fields
  
...
       POID PIN_FLD_PARENT {
             CREATE = Optional;
             MODIFY = Writeable;
}
....
}
  
## /r_service/ip (to represent Portal /service/ip storable class)
STORABLE CLASS /r_service/ip {
# list all the /r_service/ip related fields
  
...
       POID PIN_FLD_PARENT {
             CREATE = Optional;
             MODIFY = Writeable;
}
....
}
## /r_service/email (to represent Portal /service/email storable class)
STORABLE CLASS /r_service/email {
# list all the /r_service/email related fields

...
       POID PIN_FLD_PARENT {
             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";
...
}
       # For LDAP Manager
  
STORABLE CLASS /r_service IMPLEMENTATION LDAPV3 {
       ATTRVAL = "objectClass: top";
       ENTRY_TYPE = "rservice"; 
       LINK_OBJECT = "/r_user";
...
       POID PIN_FLD_PARENT {
       ATTRIBUTE = "parent";
       LINK_ATTRIBUTE = 1;
}
...
}
#
STORABLE CLASS /r_service/ip IMPLEMENTATION LDAPV3 {
# provide mapping for /r_service/ip fields
LINK_OBJECT = "/r_user";
# Provide mapping for /r_service fields.
# The link attribute is inherited from the parent.
...
       POID PIN_FLD_PARENT {
       ATTRIBUTE = "parent";
       LINK_ATTRIBUTE = 1;
}
...
}
#STORABLE CLASS /r_service/email IMPLEMENTATION LDAPV3 {
# Provide mapping for /r_service/email fields
# The link attribute is inherited from the parent.
       LINK_OBJECT = "/r_user";
...
       POID PIN_FLD_PARENT {
       ATTRIBUTE = "parent";
       LINK_ATTRIBUTE = 1;
}
...
}

    Note:

    To locate the parent /r_user object, the LDAP Data Manager uses the LOCATION attribute of the /r_user class as the base DN.

  2. Specify one of the flexible DN assignment rules to dynamically manipulate the static behavior defined in the mapping file.

    • If the DN flag indicates that the DN is a complete DN, the DN supplied is used to create the /r_service entry.

    • If the DN flag indicates that the DN is a prefix, the DN of the located /r_user entry is appended to the DNs supplied to compose the DN of the /r_service entry.

    • If the DN flag indicates that the DN is a parent, the /r_service DN supplied is appended to the value of the attribute tagged as the RDN piece. The DN of the located /r_user entry is appended to this string.

    • If you do not supply a DN, then the value of the DN of the /r_user entry will be appended to the RDN of /r_service.

Specifying Directory Tree Entries

You specify directory server entries by using the DN field, the DN qualifier field flags, and the location parameter. The DN field and the DN qualifiers let you manipulate location of entries for your directory tree, while the location parameter lets you override the mapping file location.

This section describes the controls you can use as inputs to the create, delete, read, and write operations either to manipulate directory entries or to override the base location value.

Using a Complete Distinguished Name

A complete DN is the absolute root in the directory tree for the directory server entry. To specify a complete DN, pass the complete DN of the entry in the PIN_FLD_DN field. You can optionally set PIN_FLD_DN_FLAGS to 0.

This example shows how to specify a complete DN in the input flist to the create, delete, read, and write operations at run time:

LOCATION = "o=portal.com"
PIN_FLD_DN = "cn=john, ou=dev, ou=engg, o=portal.com"
PIN_FLD_DN_FLAGS=0
  
REAL DN = "cn=john, ou=dev, ou=engg, o=portal.com"

For a complete DN, PIN_FLD_DN must match the LOCATION. For example, if the LOCATION is "o=portal.com", then the last element of PIN_FLD_DN must be "o=portal.com". The PIN_FLD_DN is the REAL DN in this case.

Using a Prefixed Distinguished Name

The prefixed DN is the RDN location in the directory tree for the directory server entry. To specify a prefixed DN, pass the prefixed DN of the entry in the PIN_FLD_DN field and set the PIN_FLD_DN_FLAGS to 1.

This example shows how to specify a prefixed DN in the input flist to the create, delete, read, and write input flists at run time:

LOCATION = "o=portal.com"
PIN_FLD_DN = "cn=john, ou=dev, ou=engg"
PIN_FLD_DN_FLAGS=1
  
REAL DN = "cn=john, ou=dev, ou=engg, o=portal.com"

The LOCATION "o=portal.com" is appended to PIN_FLD_DN "cn=john, ou=dev, ou=engg" to compose the REAL DN "cn=john, ou=dev, ou=engg, o=portal.com".

Using a Parent Distinguished Name (Create Operation Only)

A parent DN is the location of the parent of the entry in the directory tree. You can pass a parent DN only in the create operation (PCM_OP_CREATE_OBJ).

To specify a parent DN, pass the parent DN of the entry in the PIN_FLD_DN field, and set the PIN_FLD_DN_FLAGS to 2.

This example shows how to specify a parent DN in the input flist to PCM_OP_CREATE_OBJ at run time:

LOCATION = "o=portal.com"
PIN_FLD_DN = "ou=dev, ou=engg"
PIN_FLD_DN_FLAGS=2
  
REAL DN = "cn=john, ou=dev, ou=engg, o=portal.com"

The LDAP Data Manager appends the LOCATION "o=portal.com" to PIN_FLD_DN "ou=dev, ou=engg" and appends the value "ou=dev, ou=engg, o=portal.com" to the value "john" (cn) tagged as RDN_PIECE in the mapping file to compose the REAL DN "cn=john, ou=dev, ou=engg, o=portal.com".

Overriding the Base DN Location

A base DN is the root location in the directory tree for the directory server entry. You can use the location field, PIN_FLD_LOCATION to dynamically override the LOCATION value specified in the mapping file for the create, delete, delete field, and write field operations. Overrides affect the immediate operation only.

For example, if you defined this location in the mapping file (ldap.idl):

ou=engg, o=portal, dc=US

To create this entry:

mail=login1@company.com.us, ou=engg, o=portal, dc=US

And you want to create another entry in a different location such as:

ou=techdocs, o=mycompany, dc=US

You can override the value specified for the location in the mapping file to create the following entry:

mail=login2@company.com.us, ou=techdocs, o=mycompany, dc=US

To do this, you override the mapping file location by using the PIN_FLD_LOCATION field as an input to the create operation. This lets you create accounts in a different tree without LDAP Data Manager checking the LOCATION value in the mapping file.

To specify a new base location for a directory server entry, enter the new base location in the input flist:

0 PIN_FLD_LOCATION STR[0] = "mail=login2@company.com.us, ou=techdocs, o=mycompany, dc=US"

When subsequent operations are performed on this entry, you should override the mapping file location by using the PIN_FLD_LOCATION field as an input.

Reading and Searching for Directory Server Entries

You can do these operations on directory server entries:

Reading Objects from the Directory Server

You can read objects from the directory server and return an flist containing fields and values for each attribute in the directory server entry.

To read fields in a directory server entry, use the LDAP PCM_OP_READ_FLDS base opcode. This opcode reads attributes from a directory server entry from the database using the LDAP search operation

The LDAP Data Manager parses the mapping file (ldap.idl). After this file is parsed, the LDAP Data Manager creates a mapping class that contains a mapping of the /r_user class attributes to BRM fields.

The read fields opcode accepts the POID of the object that you want to read. If the POID is a type-only POID, and you provide a DN, the LDAP Data Manager uses the DN to locate the object in the directory server.

You supply the list of the fields that you want to read from the object. These fields correspond the attributes of the directory server object. For each entry that you provide in the input flist, the LDAP Data Manager queries the mapping class for the corresponding attribute name to generate the list of attributes names.

Important:

You can read only those objects that you have defined in the mapping file.

To read an object:

  1. Create the PCM_OP_READ_OBJ input flist.

  2. Specify the complete POID or DN of the directory server entry.

    Note:

    If you supply a DN then you must also supply a type-only POID. A type-only POID is a POID with a value set to -1.

Object Read examples

These examples explain how to read objects using a complete POID and a DN:

Read Object Using a Complete POID

0 PIN_FLD_POID           POID [0] 0.0.5.1 /r_user 71131 0
0 PIN_FLD_LOCATION       STR [0] "o=company.com"

Read Object Using a DN

0 PIN_FLD_POID           POID [0] 0.0.5.1 /r_user -1
0 PIN_FLD_LOCATION       STR [0] "o=company.com"
0 PIN_FLD_DN             STR [0] "uid=link51, o=company.com"
0 PIN_FLD_DN_FLAGS       INT [0] 0

Reading Attributes from the Directory Server Entry

The steps to read attributes from the directory server are similar to reading objects. However, you need to pass the fields corresponding to the attributes of the directory server object that you want to read in the input flist to PCM_OP_READ_FLDS as opposed to the objects.

To read attributes from the directory server entry:

  1. Create the PCM_OP_READ_FLDS input flist.

  2. Specify the complete POID or DN of the entry.

    Note:

    If you supply a DN then you must also supply a type-only POID. A type-only POID is a POID with a value set to -1.

  3. Pass the fields of the attributes that you want to read in the input flist.

Attribute Read Examples

These examples show how to read attributes by using a complete POID and a DN:

Read Attributes Using a Complete POID

0 PIN_FLD_POID            POID [0] 0.0.5.1 /r_user    71148
0 PIN_FLD_LOCATION        STR [0] "o=company.com"
0 PIN_FLD_ACCOUNT_NO      STR [0] "0.0.0.1 /r_account 71145 13"
0 PIN_FLD_ACCOUNT_OBJ     POID [0] 0.0.0.1 /r_account 71145
0 PIN_FLD_ACCOUNT_STATUS  STR [0] "Active"
0 PIN_FLD_LOGIN           STR [0] "link45"
0 PIN_FLD_NAME            STR [0] "link45"
0 PIN_FLD_FIRST_NAME      STR [0]  "link45"
0 PIN_FLD_LAST_NAME       STR [0] "link45"

Read Attributes Using a DN

0 PIN_FLD_POID            POID [0] 0.0.5.1 /r_user    -1 
0 PIN_FLD_LOCATION        STR [0] "o=company.com"
0 PIN_FLD_DN              STR [0] "uid=link45, o=company.com"
0 PIN_FLD_DN_FLAGS        INT [0] 0
0 PIN_FLD_ACCOUNT_NO      STR [0] "0.0.0.1 /r_account 71145 13"
0 PIN_FLD_ACCOUNT_OBJ     POID [0] 0.0.0.1 /r_account 71145
0 PIN_FLD_ACCOUNT_STATUS  STR [0] "Active"
0 PIN_FLD_LOGIN           STR [0] "link45"
0 PIN_FLD_NAME            STR [0] "link45"
0 PIN_FLD_ADDRESS         STR [0] "sdsdfs, sfsdfsd, CA 12345, USA"

Searching the Directory Server for Entries

You can search the directory server for entries that match a specified search filter. For example, you can search for an entry that has a login attribute. You can search all entries with the login attribute within a tree or sub tree.

Important:

Only those objects and attributes that you define in the mapping file can be returned by the LDAP Data Manager in the output flist.

To find LDAP objects, use the LDAP PCM_OP_SEARCH base opcode. This opcode searches the directory server based on a specified search criteria that you supply as a template in the input flist.

Important:

Only those objects and attributes that you define in the mapping file can be returned by the LDAP Data Manager in the output flist.

The LDAP Data Manager parses the mapping file (ldap.idl). After this file is parsed, the LDAP Data Manager creates a mapping class that contains a mapping of the /r_user class attributes to BRM fields.

You must supply the POID of the object for the search operation. The search opcode uses the base Distinguished Name (DN) of the POID type as a base for the search operation. You supply a search filter to this opcode as a template in PIN_FLD_TEMPLATE. The template is the filter expression with attribute names and literal values.

For each entry that matches the given search criteria, the search call returns the value of the attributes in the attribute list, if they exist in the directory entry. For multi-valued attributes an array of values is returned. This call does not return an error if it is queried for an attribute that does not exist in the directory entry.

For each attribute value or values, the class map is queried for the BRM field name corresponding to the attribute name and an entry is added to the output flist with the corresponding value for each attribute. For array attributes that are multi-valued, an array entry is created for each value.

  1. Select a search filter. See "Using the Sample LDAP Search Filters".

  2. Create the PCM_OP_SEARCH input flist.

    1. Add the POID for the PIN_FLD_POID field.

    2. Select the search filter to use as a template for the PIN_FLD_TEMPLATE field.

    3. Set PIN_FLD_ARGS to specify the arguments and value of arguments to be substituted in the search filter.

    4. Set the search scope. See "Setting the Search Scope".

  3. Call the opcode to perform the search.

    The search opcode replaces the search template criterion with attribute names (An) and values (Vn). Attribute names and values are specified in pin_fld_args[n]. In the example below, the filter translates into this search:

    (&(cn-*link*)(ipstatus r=Aktivee))

Setting the Search Scope

You can set the search scope on the directory by using the PIN_FLD_SCOPE field. The PIN_FLD_SCOPE field can have the values listed in Table 3-2:

Table 3-2 PIN_FLD_SCOPE Settings

Value Meaning

LDAP_SCOPE_SUBTREE

Default value. Searches the entire directory tree.

LDAP_SCOPE_ONELEVEL

Searches one level down the directory tree.

The search opcode returns each attribute value or values as a result in the output flist.

This example shows a sample input flist that searches for a login with the pattern "link" in it.

0 PIN_FLD_POID           POID [0] 0.0.5.1 /r_user -1 
0 PIN_FLD_LOCATION STR [0] "ou=engineering, o=company.com"
0 PIN_FLD_TEMPLATE STR [0] "(&(A1 = V1 ) ( A2 ~= V2 ))"
0 PIN_FLD_SCOPE ENUM [0] 2
0 PIN_FLD_ARGS ARRAY [1] allocated 20, used 1
1 PIN_FLD_LOGIN STR [0] "*link*"
0 PIN_FLD_ARGS ARRAY [2] allocated 20, used 1 
1 PIN_FLD_IP_STATUS STR [0] "Aktivee"

Figure 3-2 shows a sample directory tree:

Figure 3-2 Sample Directory Tree

Description of Figure 3-2 follows
Description of ''Figure 3-2 Sample Directory Tree''

If the search scope is 0 PIN_FLD_SCOPE ENUM [0] 2, entries in all branches beneath the location are searched. In this example, the searched entries include cn=scott, cn=tim, and all entries in branches under ou=research. If the search scope is 0 PIN_FLD_SCOPE ENUM [0] 1, only entries immediately below the location are searched. In this example, these include only cn=scott and cn=tim.

Specifying the Base DN

The object type (/r_user) determines the base DN of a search. The value specified for the location for /r_user in the IDL file is used as the base DN. You can override this by specifying the value for PIN_FLD_LOCATION in the input flist. The results of the search are mapped to this object class.

Searching from Different Locations

If all base class and subclass entries are under the same location, you can perform a single search from that location to find entries that are instances of the base class and subclasses that satisfy the search criteria. If the entries are under different locations, you must perform a separate search under each location to find the instances.

Example Service Storable Class Tree and Search

This is a sample service storable class definition from an .IDL file:

STORABLE CLASS /r_service IMPLEMENTATION LDAPV3 {
ATTRVAL = "objectClass: top";
ENTRY_TYPE = "rservice";
LOCATION = "ou=services, o=company.com";
.....}
  
STORABLE CLASS /r_service/ip IMPLEMENTATION LDAPV3 {
# provide mapping for /r_service/ip fields
LOCATION = "ou=ipservices, o=company.com"; 
.....}

Figure 3-3 shows the directory tree:

To locate base class and subclass entries, you must perform a search in each of the locations:

0 PIN_FLD_POID           POID [0] 0.0.5.1 /r_service -1 
0 PIN_FLD_TEMPLATE STR [0] "(A1 = V1)"
0 PIN_FLD_SCOPE ENUM [0] 2
0 PIN_FLD_ARGS ARRAY [1] allocated 20, used 1
1 PIN_FLD_LOGIN STR [0] "*john*"
Summary of Portal LDAP API operations
  
0 PIN_FLD_POID           POID [0] 0.0.5.1 /r_serviceip -1 
0 PIN_FLD_TEMPLATE STR [0] "(A1 = V1)"
0 PIN_FLD_SCOPE ENUM [0] 2
0 PIN_FLD_ARGS ARRAY [1] allocated 20, used 1
1 PIN_FLD_LOGIN STR [0] "*john*"
Summary of Portal LDAP API operations

Using the Sample LDAP Search Filters

Table 3-3 shows sample search filters that you use as templates to search the directory server entries. For information on how to search the directory server entries, see "Searching the Directory Server for Entries".

Table 3-3 LDAP Search Filters

Filter Example Arguments Modified Filter Matches

( F1=V1)

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_NAME STR [0] "*bert*"

(cn=*bert*)

All entries with the string "bert" somewhere in the name.

(F1>=Fred)

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_NAME STR [0] "Fred"

(cn>=Fred)

All entries with a common name that is lexico-graphically greater than "Fred".

(&(objectclass=person) (F1=V1))

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_EMAIL_LOGIN STR [1] "*"

(&(objectclass=person) (maillogin=*))

All people with an email address.

(F1~=V1)

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_LAST_NAME STR [0] "Jensin"

(sn~=Jensin)

All entries with a surname approximately equal to Jensin.

(Note the misspelling)

(! (F1=V1))

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_EMAIL_LOGIN STR [0] "*"

(! (mail=*))

Entries without a mail attribute.

(F1=V1)

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_POID_STR [0] "0.0.6.1 /r_user 9999 0"

(pinpoid=0.0.6.1 /r_user 9999 0)

Entries that have a pinpoid equal to the value specified.

(F1=V1)

0 PIN_FLD_ARGS ARRAY [1] allocated 10, used 1

1 PIN_FLD_DN [0] "cn=joe, ou=People, o=microsoft"

(dn= cn=joe, ou=People, o=microsoft)

Entries that have a DN equal to the value specified.

LDAP Search Limitations

The search does not return objects that are not defined in the mapping file. LDAP Data Manager treats directory server objects that are not defined in the mapping file as an error condition.

Testing Directory Server Connections

To test directory server connections, use the LDAP PCM_OP_TEST_LOOPBACK base opcode. This opcode verifies that the LDAP Data Manager and the directory server daemon/service processes are running and communicating with each other.

BRM LDAP Profile Object

For convenience, the /profile/ldap storable object holds the DN of the directory server entries corresponding to the /account storable objects. This lets you pass in a DN when you create the BRM account. BRM uses the PCM_OP_CUST_COMMIT_CUSTOMER opcode to do this.

This is useful when you create BRM accounts based on customer information already in the directory server. For example, when a new entry is created for a customer in the directory server, the DN of the entry is passed to BRM while creating the corresponding /account.

To avoid empty /profile objects, the /profile object is created only if it is passed in during account creation.

Example of how input is passed in when you use a profile object:

/profile
          PIN_FLD_POID               MS       POID        profile POID
          PIN_FLD_ACCOUNT_OBJ_POID   MR       POID        Owning Account
          PIN_FLD_NAME               MR       STR[255]    Name("LDAP Information")
          /profile/ldap
                 PIN_FLD_LDAP_INFO   MR       SUBST
                 PIN_FLD_DN          MR       TR[1024]    DN of the Event Object