Skip Headers
Oracle® Fusion Middleware Application Developer's Guide for Oracle Identity Management
11g Release 1 (11.1.1)

Part Number E10186-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

13 Oracle Directory Integration Platform PL/SQL API Reference

This chapter describes the registration API for the Oracle Directory Provisioning Integration Service. It contains the following sections:

13.1 Versioning of Provisioning Files and Interfaces

In release 9.0.2, the default interface version was version 1.1. In releases 9.0.4 and 10.1.2.0.0, the interface version defaults to version 2.0. Release 10.1.2.0.1 adds yet a third version. The administrator can use any one of these.

13.2 Extensible Event Definition Configuration

This feature is only for outbound events. It 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 are the only configured events at installation time.

An event definition (entry) consists of the following attributes.

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

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

Table 13-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
MODIFY
DELETE
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 Oracle Internet Directory. The DIP server recognizes this new event definition and propagates 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, or deleted, DIP propagates the XYZ_ADD, XYZ_MODIFY, or XYZ_DELETE event to any application concerned.

13.3 Inbound and Outbound Events

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

Table 13-2 Attributes of the Provisioning Subscription Profile

Attribute Description
EventSubscriptions

Outbound events only (multivalued).

Events for which DIP should send notification to this application. The format of this string is [USER]GROUP]:[domain_of_interest]:[DELETE|ADD|MODIFY(list_of_attributes_separated_by_comma)]

Multiple values may be specified by listing the string multiple times, each time with different values. If parameters are not specified, the following defaults are assumed: USER:organization_DN:DELETEGROUP:organization_DN:DELETE—that is, send user and group delete notifications under the organization DN.

MappingRules

Inbound events Only (multivalued).

This attribute 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. The mapping takes this form:

OBJECT_TYPE: Filter_condition: domain_of_interest

Multiple rules are allowed. In the mapping EMP:cn=users,dc=example,dc=com, the object type received is EMP. The event is meant for the domain cn=users,dc=example,dc=com. In the mapping EMP:l=AMERICA:l=AMER,cn=users,dc=example,dc=com, the object type received is EMP. The event is meant for the domain l=AMER,cn=users,dc=example,dc=com.

permittedOperations

Inbound events only (multi valued).

This attribute is used to define the types of events an application is privileged to send to the provisioning integration service. The mapping takes this form:

Event_Object: affected_domain:operation(attributes, . . . )

In the mapping IDENTITY:cn=users,dc=example,dc=com:ADD(*) the IDENTITY_ADD event is allowed for the specified domain and all attributes are also allowed. In the mapping IDENTITY:cn=users,dc=example,dc=com:MODIFY(cn,sn.mail,telephonenumber), the IDENTITY_MODIFY event is allowed only for the attributes in the list. Any extra attributes are silently ignored.


13.4 PL/SQL Bidirectional Interface (Version 3.0)

Before attempting to use Version 3.0 of the PL/SQL interface, please refer to:

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 using the following PL/SQL package specification:

DROP TYPE LDAP_EVENT_LIST_V3;
DROP TYPE LDAP_EVENT_V3;
DROP TYPE LDAP_EVENT_STATUS_LIST_V3;
DROP TYPE LDAP_ATTR_LIST_V3;
DROP TYPE LDAP_ATTR_V3;
DROP TYPE LDAP_ATTR_VALUE_LIST_V3;
DROP TYPE LDAP_ATTR_VALUE_V3;
--------------------------------------------------------------------------------------------------
-- Name: LDAP_ATTR_VALUE_V3
-- Data Type: OBJECT
-- DESCRIPTION: This structure contains values of an attribute. A list of one or
more of this object is passed in any event.
---------------------------------------------------------------------------------------------------
 
CREATE TYPE LDAP_ATTR_VALUES_V3 AS OBJECT (
     attr_value       VARCHAR2(4000),
     attr_bvalue      RAW(2048),
     attr_value_len   INTEGER
);
 
GRANT EXECUTE ON LDAP_ATTR_VALUE_V3 to public;
 
CREATE TYPE LDAP_ATTR_VALUE_LIST_V3 AS TABLE OF LDAP_ATTR_VALUE_V3;
/
GRANT EXECUTE ON LDAP_ATTR_VALUE_LIST_V3 to public;
--------------------------------------------------------------------------------------------------
-- Name: LDAP_ATTR_V3
-- 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_V3 AS OBJECT (
     attr_name        VARCHAR2(256),
     attr_type        INTEGER ,
     attr_mod_op      INTEGER,
     attr_values      LDAP_ATTR_VALUE_LIST_V3
);
 
GRANT EXECUTE ON LDAP_ATTR_V3 to public;
 
CREATE TYPE LDAP_ATTR_LIST_V3 AS TABLE OF LDAP_ATTR_V3;
/
GRANT EXECUTE ON LDAP_ATTR_LIST_V3 to public;
---------------------------------------------------------------------------------------------------
-- Name: LDAP_EVENT_V3
-- Data Type: OBJECT
-- DESCRIPTION: This structure contains event information plus the attribute List.
---------------------------------------------------------------------------------------------------
 
CREATE TYPE LDAP_EVENT_V3 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_V3 ) ;
/
 
GRANT EXECUTE ON LDAP_EVENT_V3 to public;
CREATE TYPE LDAP_EVENT_LIST_V3 AS TABLE OF LDAP_EVENT_V3;
/
GRANT EXECUTE ON LDAP_EVENT_LIST_V3 to public;
---------------------------------------------------------------------------------------------------
-- Name: LDAP_EVENT_STATUS_V3
-- 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_V3 AS OBJECT (
          event_id     VARCHAR2(32),
          status       VARCHAR2(32),
          status_msg   VARCHAR2(2048),
          object_guid  VARCHAR(32)
) ;
/
 
GRANT EXECUTE ON LDAP_EVENT_STATUS_V3 to public;
CREATE TYPE LDAP_EVENT_STATUS_LIST_V3 AS TABLE OF LDAP_EVENT_STATUS_V3;
/
GRANT EXECUTE ON LDAP_EVENT_STATUS_LIST_V3 to public;
---------------------------------------------------------------------------------------------------
-- Name: LDAP_NTFY
-- DESCRIPTION: This is the interface to be implemented by provisioning integrated
applications to send information to and receive information from the directory.
The name of the package can be customized as needed. The function and procedure
names within this package should not be changed.
 ---------------------------------------------------------------------------------------------------
 
CREATE OR REPLACE PACKAGE LDAP_NTFY AS
 
    -- The 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';
 
    -- The Attribute Type

    ATTR_TYPE_STRING            CONSTANT NUMBER  := 0;
    ATTR_TYPE_BINARY            CONSTANT NUMBER  := 1;
    ATTR_TYPE_ENCRYPTED_STRING  CONSTANT NUMBER  := 2;
 
    -- The Attribute Modification Type

    MOD_ADD      CONSTANT NUMBER  := 0;
    MOD_DELETE   CONSTANT NUMBER  := 1;
    MOD_REPLACE  CONSTANT NUMBER  := 2;
 
    -- The Event dispostions constants
 
    EVENT_SUCCESS            CONSTANT VARCHAR2(32)  :='EVENT_SUCCESS';
    EVENT_IN_PROGRESS        CONSTANT VARCHAR2(32)  :='EVENT_IN_PROGRESS';
    EVENT_USER_NOT_REQUIRED  CONSTANT VARCHAR2(32)  :='EVENT_USER_NOT_REQUIRED';
    EVENT_ERROR              CONSTANT VARCHAR2(32)  :='EVENT_ERROR';
    EVENT_ERROR_ALERT        CONSTANT VARCHAR2(32)  :='EVENT_ERROR_ALERT';
    EVENT_ERROR_ABORT        CONSTANT VARCHAR2(32)  :='EVENT_ERROR_ABORT';
 
    -- The Actual Callbacks
 
    FUNCTION GetAppEvents (events OUT LDAP_EVENT_LIST_V3)
    RETURN NUMBER;
 
    -- Return CONSTANTS
    EVENT_FOUND      CONSTANT NUMBER:= 0;
    EVENT_NOT_FOUND  CONSTANT NUMBER:= 1403;

If the provisioning server is unable to process an inbound event, it triggers an EVENT_ERROR_ALERT status, which generates a trigger in Oracle Enterprise Manager.

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

EVENT_ERROR means no errors in directory operations. The event cannot be processed for other reasons.

-- PutAppEventStatus() : DIP Server invokes this callback in the remote Data
base after processing an event it had received using the GetAppEvents()
callback.  For every event received, the DIP server sends the status event
back after processing the event.  This API will NOT be required by the
Oracle Collaboration Suite release 3.0 components.

PROCEDURE PutAppEventStatus (event_status IN LDAP_EVENT_STATUS_LIST_V3);
 
-- PutOIDEvents() : DIP Server invokes this API in the remote Database. DIP
server sends event to applications using this callback. It also expects a status
event object in response as an OUT parameter. This API needs to be implemented
by all the Oracle Collaboration Suite release 3.0 components.

PROCEDURE PutOIDEvents (event         IN  LDAP_EVENT_LIST_V3,
                       event_status  OUT LDAP_EVENT_STATUS_LIST_V3);
 
END LDAP_NTFY;
/

13.5 PL/SQL Bidirectional Interface (Version 2.0)

The PL/SQL callback interface requires that you develop a PL/SQL package that the 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 using 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;

13.6 Provisioning Event Interface (Version 1.1)

You must develop logic to consume events generated by the provisioning integration service. The interface between the application and the provisioning integration service can be table-based, or it can use PL/SQL callbacks.

The PL/SQL callback interface requires that you develop a PL/SQL package that the 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 using 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 is a notifier interface implemented by Provisioning System
--                clients to receive information about changes in Oracle Internet
--                Directory. The name of package can be customized as needed.
--                The function 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 information to and receive information from
--              Oracle Internet Directory. The name of the package can be 
--              customized as needed. The function names within this package 
--              should not be changed.
 ---------------------------------------------------------------------------------------------------

CREATE OR REPLACE PACKAGE LDAP_NTFY AS

13.6.1 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';

13.6.2 Attribute Type

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

13.6.3 Attribute Modification Type

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

13.6.4 Event Dispositions Constants

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

13.6.5 Callbacks

A callback is a function invoked by the 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 unnormalized form: if an attribute has two values, two rows are sent in the collection.

13.6.5.1 GetAppEvent()

The Oracle Directory Integration and Provisioning server invokes this API in the remote database. It is up to the application to respond with an event. The Oracle Directory Integration and Provisioning processes the event 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—it responds with EVENT_RESEND. The application is expected to resend that event when GetAppEvent() is invoked again.

If the provisioning server is able to process the event, but 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. Resending the event is not required. 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 reasons.

13.6.5.2 PutAppEventStatus()

The Oracle Directory Integration and Provisioning server invokes this callback in the remote database after processing an event it has 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);

13.6.5.3 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 a status event object in response as an OUT parameter. If a valid event status object is not sent back, or it indicates a RESEND, the Oracle Directory Integration and Provisioning server resends the event. 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;
/