This chapter describes the Oracle Communications Services Gatekeeper Parlay X 3.0 Device Capabilities/Lightweight Directory Access Protocol version 3 (LDAPv3) communication service in detail.
The Device Capabilities/LDAPv3 communication service exposes the Parlay X 3.0 Device Capabilities and Configuration set of application interfaces.
The communication service acts as an LDAP client to a directory service, connecting to the directory service using the LDAPv3.
For the exact version of the standards that the Device Capabilities/LDAPv3 communication service supports for the application-facing interfaces and the network protocols, see Services Gatekeeper Statement of Compliance.
The Parlay X 3.0 Device Capabilities/LDAPv3 communication service sends requests to any LDAPv3-compliant directory server with a device's address (usually a phone number), and in return receives one of the following device identifiers:
The device's unique device ID, device or model name, and a link to the User Agent Profile XML file.
The device's equipment identifier (for example, its IMEI)
For information about the SOAP-based interface for the Parlay X 3.0 Device Capabilities communication service, see the discussion about Parlay X 3.0 Part 18 Device capabilities in Services Gatekeeper Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion about RESTful device capabilities in Services Gatekeeper Application Developer's Guide.
The RESTful Service Call Notification interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating service level agreements (SLAs) and reading charging data records (CDRs), and so on, they are the same.
The Parlay X 3.0 Device Capabilities/LDAPv3 communication service generates event data records (EDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.
See "Events, Alarms, and Charging" for more information.
Table 14-1 lists the IDs of the EDRs created by the Device Capabilities/LDAPv3 communication service. This list does not include EDRs created when exceptions are thrown.
The Device Capabilities/LDAPv3 communication service does not generate any CDRs by default.
Table 14-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
This section describes the properties and workflow for the Parlay X 3.0 Device Capabilities/LDAPv3 plug-in instance.
It also includes a description of how to create an LDAP-to-XML mapping file.
Table 14-3 lists the technical specifications for the communication service.
Table 14-3 Properties for Parlay X 3.0 Device Capabilities/LDAPv3
Property | Description |
---|---|
Managed object in Administration Console |
To access the object, select domain_name, then OCSG, then server_name, then Communication Services, then plug-in_instance_id, in that order. |
MBean |
Domain=oracle.ocsg.plugin.dc.ldap.management Name=wlng_nt_device_capabilities_px30 InstanceName=Device_cap Type=oracle.ocsg.plugin.dc.ldap.management.DeviceCapabilitiesLdapMBean |
Network protocol plug-in service ID |
Plugin_px30_decvice_capabilities_ldap |
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. |
Supported Address Formats |
tel, id, imsi, ipv4/ipv6 |
Application-facing interface |
com.bea.wlcp.wlng.px30.plugin.DeviceCapabilitiesPlugin |
Service type |
DeviceCapabilities |
Exposes to the service communication layer a Java representation of: |
Device Capabilities/LDAP |
Interfaces with the network nodes using: |
LDAP |
Deployment artifact NT EAR wlng_nt_device_capabilities_px30.ear |
px30_device_capabilities.jar and Plugin_px30_device_capabilities_ldap.jar. |
Deployment artifact AT EAR: SOAP Only wlng_at_device_capabilities_px30_soap.ear |
Ipx30_device_capabilities.war |
Deployment artifact AT EAR: wlng_at_device_capabilities_px30.ear |
px30_device_capabilities.jar and Plugin_px30_device_capabilities_ldap.jar |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in service ID as listed in the "Properties for Parlay X 3.0 Device Capabilities/LDAPv3 Plug-in" section.
Using the Administration Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
Define the characteristics of the LDAP server to connect to using these attributes:
Using "Attribute: Schema", define the XML schema.
See "Creating an LDAP-to-XML Mapping File" for a description of the schema and "Configuration Workflow for Device Capabilities/LDAPv3 Plug-in" for a description of the mappings.
Define the connection pool characteristics for the connection:
Set up the routing rules to the plug-in instance. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 3.0 Device Capabilities/LDAPv3 Plug-in" section.
If required, create and load a node SLA. For details see the discussion about defining global node and service provider group node SLAs and managing SLAs in Services Gatekeeper Accounts and SLAs Guide.
Provision the service provider and application accounts. For information, see Services Gatekeeper Portal Developer's Guide.
You can create multiple Device Capabilities/LDAPv3 plug-in instances, each with a different LDAP configuration. Each plug-in instance could point to a different LDAP tree or even a different LDAP server.
Each Device Capabilities/LDAPv3 plug-in instance routes requests to an LDAP stack (LDAPJDK 4.1). The LDAP library (physical connection) is specified using the instanceId field. The LDAP stack is included as a library in the network tier EAR package.
The LDAP library must have the device capabilities (Name, agentProfileRef, and deviceId (IMEI)) stored as attributes in a single LDAP entry indexed by address. You can redirect a plug-in to a different LDAPv3 library by specifying a new Distinguished Name (DN) and schema as long as the device capabilities are all available from a single LDAP entry.
An XSD schema that you create maps the URI format (for example, tel: or imsi:) to an associated query string; this file does not affect the LDAP database.
You need to map the Device Capabilities communication service SOAP request data to an LDAP query string that matches the subscriber information in your LDAP directory. You do this by defining an XML file to map the data and an XSD schema to validate the XML.
Example 14-1 shows a sample LDAP query XSD schema for the sample XML data shown in Example 14-2. This XML file maps the tel:1234 address to msisdn=1234,domainName=msisdnD. The resulting LDAP query for this example is:
(&(msisdn=1234)(objectClass=*))
in
domainName=msisdnD,%Base DN%
.
The Base DN is configured using Attribute: BaseDN.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="LdapConfig"> <xs:complexType> <xs:sequence> <xs:element name="Keys" type="KeySet" minOccurs="1" maxOccurs="unbounded"/> <xs:element name="LdapObject" type="LdapObject" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="KeyObject"> <xs:sequence> <xs:element name="uriScheme" type="xs:string" minOccurs="1" maxOccurs="1"/> <xs:element name="addressKeyName" type="xs:string" minOccurs="1" maxOccurs="1"/> <xs:element name="objectKeyName" type="xs:string" minOccurs="0" maxOccurs="1"/> <xs:element name="objectKeyValue" type="xs:string" minOccurs="0" maxOccurs="1"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="optional"/> </xs:complexType> <xs:complexType name="KeySet"> <xs:sequence> <xs:element name="Key" type="KeyObject" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="required"/> </xs:complexType> <xs:complexType name="LdapObject"> <xs:sequence> <xs:element name="ObjectKeySet" type="xs:string" minOccurs="0" maxOccurs="1"/> </xs:sequence> <xs:attribute name="id" type="xs:string" use="required"/> <xs:attribute name="keyName" type="xs:string" use="required"/> <xs:attribute name="keyValue" type="xs:string" use="required"/> </xs:complexType> </xs:schema>
Example 14-2 shows sample XML data that matches the LDAP query XSD file in Example 14-1.
<?xml version="1.0" encoding="UTF-8"?> <LdapConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation='sp_config.xsd'> <Keys id="sample"> <Key> <uriScheme>tel</uriScheme> <addressKeyName>msisdn</addressKeyName> <objectKeyName>domainName</objectKeyName> <objectKeyValue>msisdnD</objectKeyValue> </Key> </Keys> </LdapConfig>
You need to create your own LDAP query XSD file to map your LDAP SOAP request elements to your LDAP database elements. The LDAP query XSD file must define the following objects based on their elements, listed in Table 14-4:
LdapObject: A KeySet holder.
KeySet: A collection of KeyObjects. Sets of keys are used because there may be several ways to reach a certain node in the tree. One LDAP plug-in instance can be configured with several KeySets and can provide the link between the search key in the Extended Web Services interface and the LDAP tree.
KeyObject: An entry point to the LDAP tree that provides the link between the search key in the Extended Web Services interface and the LDAP tree.
Object | Element | Description |
---|---|---|
LdapObject |
ObjectKeySet |
Defines the KeySet through which it can be reached. Refers to the ID attribute of a defined KeySet. |
LdapObject |
id |
The identity of the LdapObject. Can be referenced from other LdapObjects through the ParentObjectId field. |
LdapObject |
keyName |
The name of the key through which the LdapObject can be reached. |
LdapObject |
keyValue |
The value of the key through which the LdapObject can be reached. |
KeyObject |
uriScheme |
Defines the URI scheme of the address for which this key applies. |
KeyObject |
addressKeyName |
Defines the key name with which the address value is associated. |
KeyObject |
objectKeyName |
Provides the possibility of defining the addressing key of a possible tree node above the node that is reached by the address key (that is, like the domain object in the 3DS directory information tree). |
KeyObject |
objectKeyValue |
See objectKeyName. Defines the value of the key. |
KeyObject |
id |
The identity of the key. Used only for descriptive purposes. |
KeySet |
Key |
All keys in the KeySet |
KeySet |
id |
The identity of the KeySet. Used when associating an LdapObject with a KeySet. |
This section describes the attributes and operations for configuration and maintenance:
Scope: Cluster
Format: String
Specifies a Distinguished Name (DN) in the LDAP server.
Use "Operation: apply" to make changes to this attribute take effect.
Example:
cn=admin,o=acompany,c=uk
Scope: Cluster
Format: String
Specifies the password associated with theAttribute: AuthDN.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: String
Specifies the base Distinguished Name (DN) for the LDAP database in use.
Use "Operation: apply" to make changes to this attribute take effect.
Example:
o=acompany,c=uk
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the maximum time to wait for an LDAP connection to be established. If the related timer expires, a retry is performed. See "Attribute: recoverTimerInterval" for more information.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: String
Specifies the DeviceId of the target LDAP entry.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: String
Specifies the DeviceName of the target LDAP entry.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: String
Specifies the DeviceProfileURL of the target LDAP entry.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: String
Specifies the host name or IP address of the LDAP server to connect to.
Use "Operation: apply" to make changes to this attribute take effect.
Examples:
myldapserver.mycompany.org 192.168.0.14
Read-only.
Scope: Local
Unit: Not applicable
Values: active, update_pending, or deactive. Table 14-5 describes each of these values and their implications.
Format: String
Table 14-5 LDAP Server Connection Status
Status | Description |
---|---|
active |
The connection is active. The plug-in instance accepts requests. |
update_pending |
The connection is temporarily unavailable due to an update of the configuration settings. The plug-in instance does not accept requests. |
deactive |
The connection is inactive. The plug-in instance does not accept requests. Reasons for this entering this state include:
|
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the maximum number of connections in the LDAP connection pool.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the minimum number of connections to establish using connections from the LDAP connection pool.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the port number of the LDAP server to connect to.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Format: Integer
Unit: Seconds
Default Value: 300
Specifies the time to wait before performing an LDAP connection retry after an LDAP connection error. Should be at least twice the time defined in the ConnTimeout attribute. See "Attribute: ConnTimeout" for more information.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Unit: Not applicable
Format: String
The LDAP schema to use.
Use "Operation: apply" to make changes to this attribute take effect.
Scope: Cluster
Applies attribute changes.
Signature:
apply()
Scope: Cluster
Format: String
Updates the schema URL to use when performing lookups in the LDAP database.
During the update, the LDAP connection is temporarily unavailable and the connection status is update_pending. See Table 14-5 for more information.
Signature:
pdateSchemaURL(SchemaURL:String)
Table 14-6 explains that the schemaURL parameter is the LDAP database schema URL to use.