User Import approved Application Program Interface
It is recognized that some customers have the resources and expertise available in order to construct their own method of transferring User data from a source system into OLIB. Typically this can be problematic during upgrades and with changes in functionality. In order to provide a future-proof OLIB User population method the interface detailed below is the only interface that is supported for population of User records by direct connection to the database.
The calls detailed below are used internally by the manual and scheduled User Import process and will be updated with each new release to cater for new functionality; new columns (mandatory, defaulted etc) and new validation on the data being imported.
A section has been added to the end of this document to highlight any changes that are needed between OLIB releases.
For each element of each User record (equating to a line in a file) a PL/SQL call should be made to the following procedure that is owned by the OLIB configuration user:-
UserImport.NewTag(:Tag, :Value, :MessageBuffer);
The Tag and Value parameters here are the same as the tags and values that would be placed on each line in a file.
MessageBuffer: A VARCHAR2(4000 BYTE) buffer for holding the result of the procedure call. See below for more information.
To complete each import record and save the information provided in the OLIB system, a call such as the following should be made:-
UserImport.NewTag('*', null, :MessageBuffer);
MessageBuffer can be returned with the following information:
A value stating with ‘FAIL RECORD:’ Indicating that there was a problem with this record and it has not been transferred. The remainder of the message gives the detail of the problem.
A value stating with ‘FAIL LOAD:’ Indicating that there is a problem that does not relate specifically to this record and the transfer should be ceased. The remainder of the message gives the detail of the problem.
NULL: indicating that the tag was processed satisfactorily and the transfer can continue.
If the OLIB system is accessed over a database link then a synonym for the UserImport package can be created in the source schema. For example:
create synonym UserImport for UserImport@olib.dblink;
In addition to the tags, there are 3 settings that can be amended to suit the data being transferred. These, and their defaults, are itemized below:-
UserImport.DefATP := null; -- Default Address Type
UserImport.DefLoc := 'MAIN'; -- Default User Location
UserImport.DateFormat := 'DD-MON-YYYY' -- Default date format
The grouping, sequence and repetition rules apply for each tag as if the tags were being placed into a file. To illustrate the API the example record given above is shown below, partly converted into an SQL*Plus script:-
var MessageBuffer varchar2(4000) declare procedure handle_error is begin if :MessageBuffer like 'FAIL RECORD:%' then { call your procedure for logging an error } raise VALUE_ERROR; elsif :MessageBuffer like 'FAIL LOAD:%' then { call your procedure for logging an error } raise_application_error(-20000, :MessageBuffer); elsif :MessageBuffer is not null then -- There may be messages specific to the tag -- that should not prevent the record completing { call your procedure for logging an error } :MessageBuffer := null; end if; end handle_error; begin for User_record in (select { details from your application } from ... where ... ) loop begin UserImport.NewTag('MATCH', 'SECCODE', :MessageBuffer); handle_error; UserImport.NewTag('SEC', User_record.UniqueID, :MessageBuffer); handle_error; UserImport.NewTag('SUR', User_record.surname, :MessageBuffer); handle_error; UserImport.NewTag('FORE', User_record.forenames, :MessageBuffer); handle_error; … UserImport.NewTag('*', null, :MessageBuffer); handle_error; UserImport.NewTag('SEC', User_record.UniqueID, :MessageBuffer); handle_error; UserImport.NewTag('HOUSE', User_record.Address1, :MessageBuffer); handle_error; UserImport.NewTag('STR', User_record.Address2, :MessageBuffer); handle_error; … UserImport.NewTag('*', null, :MessageBuffer); handle_error; exception when VALUE_ERROR then { call your procedure for logging an error } end; end loop; end; /