11
Provisioning Integration API Reference

This chapter contains reference information for the Oracle Directory Provisioning Integration Service Registration API. It contains the following sections:

Versioning of Provisioning Files and Interfaces

In the Oracle Internet Directory release 9.0.2, the default interface version was version 1.1. In release 9.0.4, the interface version defaults to version 2.0, but the administrator can set this back to version 1.1 to maintain the previous interface.

Extensible Event Definition Configuration

This feature is meant only for OUTBOUND events. This feature addresses the ability to define a new EVENT at run time so that the Provisioning Integration service can interpret a change in Oracle Internet Directory and determine whether an appropriate event is to be generated and propagated to an application. The following events will be the only configured events at the installation time.

An Event Definition (entry) consists of the following attributes.

Event Object Type (orclODIPProvEventObjectType): This specifies the type of Object the Event is associated with. E.g The object could be a USER, GROUP, IDENTITYetc.
LDAP Change Type (orclODIPProvEventChangeType): This indicates what all kinds of LDAP operations can generate an Event for this type of Object. (e.g ADD, MODIFY, DELETE)
Event Criteria (orclODIPProvEventCriteria): The additional selection criteria that qualifies an LDAP entry to be of a specific Object Type. For example, Objectclass=orclUserV2 means that any LDAP entry which satisfies this criteria can be qualified as this Object Type and any change to this entry can generate appropriate event(s).

The object class that holds the above attributes is orclODIPProvEventTypeConfig. The container cn=ProvisioningEventTypeConfig,cn=odi,cn=oracle internet directory is used to store all the event type configurations.

Table 11-1 lists the event definitions predefined as a part of the installation.

Table 11-1 Predefined Event Definitions

Event Object Type	LDAP Change Type	Event Criteria
ENTRY	ADD, MODIFY, DELETE	OBJECTCLASS=*
USER	ADD, MODIFY, DELETE	OBJECTCLASS=interorgperson OBJECTCLASS=orcluserv2
IDENTITY	ADD, MODIFY, DELETE	OBJECTCLASS=interorgperson OBJECTCLASS=orcluserv2
GROUP	ADD, MODIFY, DELETE	OBJECTCLASS=orclgroup OBJECTCLASS=groupofuniquenames
SUBSCRPTION	ADD, MODIFY, DELETE	OBJECTCLASS=orclservicerecepient
SUBSCRIBER	ADD, DELETE, MODIFY	OBJECTCLASS=orclsubscriber

The container cn=ProvisioningEventTypeConfig,cn=odi,cn=oracle internet directory is used to store all the event definition configurations. LDAP configuration of the predefined event definitions is as follows:

dn: orclODIPProvEventObjectType=ENTRY,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: ENTRY
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=*
objectclass: orclODIPProvEventTypeConfig

dn: 
orclODIPProvEventObjectType=USER,cn=ProvisioningEventTypeConfig,cn=odi,cn=oracle 
internet directory
orclODIPProvEventObjectType: USER
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=InetOrgPerson
orclODIPProvEventCriteria: objectclass=orcluserv2
objectclass: orclODIPProvEventTypeConfig

dn: orclODIPProvEventObjectType=IDENTITY,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: IDENTITY
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=inetorgperson
orclODIPProvEventCriteria: objectclass=orcluserv2
objectclass: orclODIPProvEventTypeConfig

dn: orclODIPProvEventObjectType=GROUP,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: GROUP
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=orclgroup
orclODIPProvEventCriteria: objectclass=groupofuniquenames
objectclass: orclODIPProvEventTypeConfig

dn: 
orclODIPProvEventObjectType=SUBSCRIPTION,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: SUBSCRIPTION
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=orclservicerecepient
objectclass: orclODIPProvEventTypeConfig

dn: 
orclODIPProvEventObjectType=SUBSCRIBER,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: SUBSCRIBER
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=orclsubscriber
objectclass: orclODIPProvEventTypeConfig

To define a new event of Object type XYZ (which is qualified with the object class "objXYZ"), create the following entry in OID. The DIP server would recognize this new EVENT definition and propagate events if necessary to applications that subscribe to this event.

dn: orclODIPProvEventObjectType=XYZ,cn=ProvisioningEventTypeConfig,cn=odi, 
cn=oracle internet directory
orclODIPProvEventObjectType: XYZ
orclODIPProvEventLDAPChangeType: Add
orclODIPProvEventLDAPChangeType: Modify
orclODIPProvEventLDAPChangeType: Delete
orclODIPProvEventCriteria: objectclass=objXYZ
objectclass: orclODIPProvEventTypeConfig

This means that if an LDAP entry with the object class "objXYZ" is added/modified/deleted, DIP will propagate the XYZ_ADD/XYZ_MODIFY/XYZ_DELETE event respectively to any application concerned.

INBOUND And OUTBOUND Events

An application can register as a supplier as well as a consumer of events. The provisioning subscription profile has the attributes described in Table 11-2 .

Table 11-2 Attributes of the Provisioning Subscription Profile

Attribute	Description
EventSubscriptions	OUTBOUND Events only. (Multi valued) This is same as it was in the previous release. Events for which DIP should send notification to this application. Format of this string :"[USER]GROUP]:[Domain of interest>]:[DELETE\|ADD\|MODIFY(<list of attributes separated by comma>)]" Multiple values may be specified by listing the parameter multiple times each with different values. If not specified the following defaults are assumed: USER:<org. DN>:DELETEGROUP:<org. DN>:DELETE--that is, send user and group delete notifications under the organization DN.
MappingRules	INBOUND Events Only (Multi valued) New to this release This is used to map the type of object received from an application and a qualifying filter condition to determine the domain of interest for this event. OBJECT_TYPE: Filter condition: Domain Of Interest Multiple rules are allowed. For example: EMP::cn=users,dc=acme,dc=com This means that if the object type received is "EMP", the event is meant for the domain "cn=users,dc=acme,dc=com" EMP:l=AMERICA:l=AMER,cn=users,dc=acme,dc=com This means that if the object type received is "EMP", and the event has the attribute l (locality) and its value is "AMERICA", the event is meant for the domain "l=AMER,cn=users,dc=acme,dc=com"
permittedOperations	INBOUND Events Only (Multi valued) New to this release. This is used to define the types of EVENT an application is privileged to send to the Provisioning Integration Service. Format : Event_Object: Affected Domain:Operation(Attributes,...) For example: IDENTITY:cn=users,dc=acme,dc=com:ADD(*) This means that IDENTITY_ADD event is allowed for the specified domain and all attributes are also allowed. IDENTITY:cn=users,dc=acme,dc=com:MODIFY(cn,sn.mail,telephonenumber) This means that IDENTITY_MODIFY is allowed for only the attributews in the list. Any extra attributes are silently ignored.

Attribute

Description

EventSubscriptions

OUTBOUND Events only. (Multi valued)

This is same as it was in the previous release. Events for which DIP should send notification to this application. Format of this string :"[USER]GROUP]:[Domain of interest>]:[DELETE|ADD|MODIFY(<list of attributes separated by comma>)]"

Multiple values may be specified by listing the parameter multiple times each with different values. If not specified the following defaults are assumed: USER:<org. DN>:DELETEGROUP:<org. DN>:DELETE--that is, send user and group delete notifications under the organization DN.

MappingRules

INBOUND Events Only (Multi valued) New to this release This is used to map the type of object received from an application and a qualifying filter condition to determine the domain of interest for this event.

OBJECT_TYPE: Filter condition: Domain Of Interest

Multiple rules are allowed.

For example:

EMP::cn=users,dc=acme,dc=com

This means that if the object type received is "EMP", the event is meant for the domain "cn=users,dc=acme,dc=com"
EMP:l=AMERICA:l=AMER,cn=users,dc=acme,dc=com

This means that if the object type received is "EMP", and the event has the attribute l (locality) and its value is "AMERICA", the event is meant for the domain "l=AMER,cn=users,dc=acme,dc=com"

permittedOperations

INBOUND Events Only (Multi valued)

New to this release.

This is used to define the types of EVENT an application is privileged to send to the Provisioning Integration Service.

Format : Event_Object: Affected Domain:Operation(Attributes,...) For example:

IDENTITY:cn=users,dc=acme,dc=com:ADD(*)

This means that IDENTITY_ADD event is allowed for the specified domain and all attributes are also allowed.
IDENTITY:cn=users,dc=acme,dc=com:MODIFY(cn,sn.mail,telephonenumber)

This means that IDENTITY_MODIFY is allowed for only the attributews in the list. Any extra attributes are silently ignored.

PL/SQL Bidirectional Interface (Version 2.0)

The PL/SQL callback interface requires you to develop a PL/SQL package that Oracle Provisioning Integration Service invokes in the application specific database. Choose any name for the package, but be sure to use the same name when you register the package at

Subscription time. Implement the package by the following PL/SQL package specification:

DROP TYPE LDAP_EVENT;
DROP TYPE LDAP_EVENT_STATUS;
DROP TYPE LDAP_ATTR_LIST;
DROP TYPE LDAP_ATTR;
--------------------------------------------------------------------------------
-- Name: LDAP_ATTR
-- Data Type: OBJECT

DESCRIPTION: This structure contains details regarding an attribute. A list of 
one or more of this object is passed in any event.
--------------------------------------------------------------------------------
-------------------
CREATE TYPE LDAP_ATTR AS OBJECT (
     attr_name        VARCHAR2(256),
     attr_value       VARCHAR2(4000),
     attr_bvalue      RAW(2048),
     attr_value_len   INTEGER,
     attr_type        INTEGER ,
     attr_mod_op      INTEGER
);

GRANT EXECUTE ON LDAP_ATTR to public;

CREATE TYPE LDAP_ATTR_LIST AS TABLE OF LDAP_ATTR;
/
GRANT EXECUTE ON LDAP_ATTR_LIST to public;

--------------------------------------------------------------------------------
-------------------
-- Name: LDAP_EVENT
-- Data Type: OBJECT
-- DESCRIPTION: This structure contains event information plus the attribute 

-- list
--------------------------------------------------------------------------------
-------------------

CREATE TYPE LDAP_EVENT AS OBJECT (
          event_type  VARCHAR2(32),
          event_id    VARCHAR2(32),
          event_src   VARCHAR2(1024),
          event_time  VARCHAR2(32),
          object_name VARCHAR2(1024),
          object_type VARCHAR2(32),
          object_guid VARCHAR2(32),
          object_dn   VARCHAR2(1024),
          profile_id  VARCHAR2(1024),
          attr_list   LDAP_ATTR_LIST ) ;
/

GRANT EXECUTE ON LDAP_EVENT to public;

--------------------------------------------------------------------------------
-------------------
-- Name: LDAP_EVENT_STATUS
-- Data Type: OBJECT
-- DESCRIPTION: This structure contains information that is sent by the consumer 
of an                   
                                event to the supplier in response to the actual 
event.
 
--------------------------------------------------------------------------------
-------------------

CREATE TYPE LDAP_EVENT_STATUS AS OBJECT (
          event_id    VARCHAR2(32),
          orclguid  VARCHAR(32),
          error_code  INTEGER,
          error_String VARCHAR2(1024),
          error_disposition VARCHAR2(32)) ;
/

GRANT EXECUTE ON LDAP_EVENT_STATUS to public;

Provisioning Event Interface (Version 1.1)

As stated in "Development Tasks for Provisioning Integration", you must develop logic to consume events generated by the Oracle Directory Provisioning Integration Service.The PL/SQL callback interface requires you to develop a PL/SQL package that Oracle Directory Provisioning Integration Service invokes in the application-specific database. Choose any name for the package, but be sure to use the same name when you register the package at subscription time. Implement the package by the following PL/SQL package specification:

Rem
Rem      NAME
Rem         ldap_ntfy.pks - Provisioning Notification Package Specification.
Rem

DROP TYPE LDAP_ATTR_LIST;
DROP TYPE LDAP_ATTR;

-- LDAP ATTR
----------------------------------------------------------------
--
--  Name        : LDAP_ATTR
--  Data Type   : OBJECT
--  DESCRIPTION : This structure contains details regarding 
--                an attribute. 
--
----------------------------------------------------------------
CREATE TYPE LDAP_ATTR AS OBJECT (                                
     attr_name        VARCHAR2(255),
     attr_value       VARCHAR2(2048),
     attr_bvalue      RAW(2048),
     attr_value_len   INTEGER,
     attr_type        INTEGER  -- (0 - String, 1 - Binary)
     attr_mod_op      INTEGER
);
/
 GRANT EXECUTE ON LDAP_ATTR to public;

-------------------------------------------------------------
--
--  Name        : LDAP_ATTR_LIST
--  Data Type   : COLLECTION
--  DESCRIPTION : This structure contains collection 
--                of attributes.
--
-------------------------------------------------------------
CREATE TYPE LDAP_ATTR_LIST AS TABLE OF LDAP_ATTR;
/
 GRANT EXECUTE ON LDAP_ATTR_LIST to public;

-------------------------------------------------------------------------------
--
--  NAME        : LDAP_NTFY
--  DESCRIPTION : This a notifier interface implemented by Provisioning System
--               clients to receive information about changes in OID.
--               The name of package can be customized as needed. 
--               The functions names within this package SHOULD NOT be changed.
--
--
-------------------------------------------------------------------------------
CREATE OR REPLACE PACKAGE LDAP_NTFY AS

--
-- LDAP_NTFY data type definitions
--


-- Event Types
USER_DELETE               CONSTANT VARCHAR2(256) := 'USER_DELETE';
USER_MODIFY               CONSTANT VARCHAR2(256) := 'USER_MODIFY';
GROUP_DELETE              CONSTANT VARCHAR2(256) := 'GROUP_DELETE';
GROUP_MODIFY              CONSTANT VARCHAR2(256) := 'GROUP_MODIFY';

-- Return Codes (Boolean)
SUCCESS                   CONSTANT NUMBER  := 1;
FAILURE                   CONSTANT NUMBER  := 0;

-- Values for attr_mod_op in LDAP_ATTR object.
MOD_ADD                   CONSTANT NUMBER  := 0;
MOD_DELETE                CONSTANT NUMBER  := 1;
MOD_REPLACE               CONSTANT NUMBER  := 2;
--------------------------------------------------------------------------------
-------------------
-- Name: LDAP_NTFY
-- DESCRIPTION: This is the interface to be implemented by Provisioning System

-- clients to send/receive information to/from OID. The name of

-- Package can be customized as needed.

-- The functions names within this package SHOULD NOT be changed.
 
--------------------------------------------------------------------------------
-------------------

CREATE OR REPLACE PACKAGE LDAP_NTFY AS

Predefined Event Types

ENTRY_ADD            CONSTANT VARCHAR2 (32)  := 'ENTRY_ADD';
ENTRY_DELETE      CONSTANT VARCHAR2 (32)  := 'ENTRY_DELETE';
ENTRY_MODIFY     CONSTANT VARCHAR2 (32) := 'ENTRY_MODIFY';

USER_ADD                CONSTANT VARCHAR2 (32)  := 'USER_ADD';
USER_DELETE          CONSTANT VARCHAR2 (32) := 'USER_DELETE';
USER_MODIFY CONSTANT VARCHAR2(32) := 'USER_MODIFY';


IDENTITY_ADD          CONSTANT VARCHAR2 (32) := 'IDENTITY_ADD';
IDENTITY_DELETE   CONSTANT VARCHAR2 (32) := 'IDENTITY_DELETE';
IDENTITY_MODIFY  CONSTANT VARCHAR2 (32) := 'IDENTITY_MODIFY';

GROUP_ADD               CONSTANT VARCHAR2 (32) := 'GROUP_ADD';
GROUP_DELETE         CONSTANT VARCHAR2 (32) := 'GROUP_DELETE';
GROUP_MODIFY         CONSTANT VARCHAR2 (32) := 'GROUP_MODIFY';

SUBSCRIPTION_ADD         CONSTANT VARCHAR2(32) := 'SUBSCRIPTION_ADD';
SUBSCRIPTION_DELETE  CONSTANT VARCHAR2(32) := 'SUBSCRIPTION_DELETE';
SUBSCRIPTION_MODI       CONSTANT VARCHAR2(32) := 'SUBSCRIPTION_MODIFY';

SUBSCRIBER_ADD          CONSTANT VARCHAR2(32) := 'SUBSCRIBER_ADD';
SUBSCRIBER_DELETE    CONSTANT VARCHAR2(32) := 'SUBSCRIBER_DELETE';
SUBSCRIBER_MODIFY   CONSTANT VARCHAR2(32) := 'SUBSCRIBER_MODIFY';

Attribute Type

ATTR_TYPE_STRING             CONSTANT NUMBER  := 0;
ATTR_TYPE_BINARY             CONSTANT NUMBER  := 1;
ATTR_TYPE_ENCRYPTED_STRING   CONSTANT NUMBER  := 2;

Attribute Modification Type

MOD_ADD              CONSTANT NUMBER  := 0;
MOD_DELETE           CONSTANT NUMBER  := 1;
MOD_REPLACE          CONSTANT NUMBER  := 2;

Event Dispostions Constants

EVENT_SUCCESS             CONSTANT VARCHAR2(32)  := 'EVENT_SUCCESS';
EVENT_FAILURE             CONSTANT VARCHAR2(32)  := 'EVENT_FAILURE';
EVENT_RESEND              CONSTANT VARCHAR2(32)  := 'EVENT_RESEND';

Callbacks

A callback function invoked by the Oracle Directory Provisioning Integration Service to send or receive notification events. While transferring events for an object, the related attributes can also be sent along with other details. The attributes are delivered as a collection (array) of attribute containers, which are in un-normalized form--that is, if an attribute has two values then two rows would be sent in the collection.

GetAppEvent()

The Oracle directory integration and provisioning server invokes this API in the remote database. It is up to the appliction to respond with an event. Once the Oracle Directory Integration and Provisioning platform gets the event, it processes the it and sends the status back using the PutAppEventStatus() callback. The return value of GetAppEvent() indicates whether an event is returned or not.

FUNCTION GetAppEvent (event OUT LDAP_EVENT)
RETURN NUMBER;

-- Return CONSTANTS
EVENT_FOUND         CONSTANT NUMBER  := 0;
EVENT_NOT_FOUND     CONSTANT NUMBER  := 1403;

If the provisioning server is not able to process the event--that is, it runs into some type of LDAP error--then it responds with EVENT_RESEND and the application is expected to resend that event in the future when GetAppEvent() is invoked again.

If the provisioning server is able to process the event, but it finds that the event cannot be processed--for example, the user to be modified does not exist, or the user to be subscribed does not exist, or the user to be deleted does not exist--then it responds with EVENT_ERROR to indicate to the application that something was wrong. It is not required to resend the event. It is up to the application to handle the event.

Note the difference between EVENT_RESEND and EVENT_ERROR in the previous discussion. EVENT_RESEND means that it was possible to apply the event but the server could not. If it gets the event again, it might succeed.

EVENT_ERROR means there is no error in performing directory operations, but the event could not be processed due to other reaons.

PutAppEventStatus()

The Oracle directory integration and provisioning server invokes this callback in the remote database after processing an event it had received using the GetAppEvent() callback. For every event received, the Oracle directory integration and provisioning server sends the status event back after processing the event.

PROCEDURE PutAppEventStatus (event_status IN LDAP_EVENT_STATUS);

PutOIDEvent()

The Oracle directory integration and provisioning server invokes this API in the remote database. It sends event to applications using this callback. It also expects n status event object in response as an OUT parameter. If valid event status object is not sent back or it indicates a RESEND, then the Oracle directory integration and provisioning server resends this event again. In case of EVENT_ERROR, the server does not resend the event.

PROCEDURE PutOIDEvent (event  IN  LDAP_EVENT,   event_status  OUT LDAP_EVENT_
STATUS);
END LDAP_NTFY;
/

11 Provisioning Integration API Reference