WHITE PAPER : Understanding and Using Web ADI in Oracle HRMS

Understanding and Using Web ADI in Oracle HRMS [ID 360105.1] Modified 25-JUL-2011 Type WHITE PAPER Status PUBLISHED

Understanding and Using Web ADI in Oracle HRMS

Product: Oracle Human Resources Minimum Version: 11.5.9

An Oracle White Paper Abstract

Understanding and Using Web ADI in Oracle HRMS.

Document History
Authors : Steve Cooper, Nick Riordan Create Date : 03-MAR-2006 Last Update Date : 11-MAR-2011 Expiration Date : Other Information : Web ADI was included from HRMS Family Pack H

Table of Contents
1. 2. 3. 4. 5. 6. 7. 8. 9. General Introduction History Patching Getting Started Concepts Creating an Integrator Running a Seeded Download Integrator Running a Seeded Upload Integrator A Step by Step Guide to Creating HRMS Integrators o a) Define a Download style Integrator and Associate with a Form o b) Define a GENERAL Update style Integrator o c) Define a GENERAL Create style Integrator o d) Define a Standalone Download Integrator with an Additional Where clause 10. Letters 11. Technical

12. Related Documents

General Introduction
Web Applications Desktop Integrator (Web ADI) is a self-service Oracle Application. Web ADI generates Microsoft Excel or Word documents on your desktop, and downloads the data you have selected from the application to be viewed, or modified and uploaded. It can also be used to load legacy data into Oracle HRMS, and allows you to manage the Mail Merge process.

History
Previously in Oracle HRMS this functionality was provided by Application Data Export (ADE), a client based tool. Effective R12 (Release 12) HRMS ADE will no longer be supported, please review Note:339987.1 for further information. WebADI, being server based makes maintenance for users somewhat simpler and less costly. WebADI is a generic tool which is in use across the entire E-Business Suite. To aid the customer, HR development have supplied a selection of example HR integrators and provided a framework for customers to add their own enhancements. These features were introduced into HRMS family packs from FP.H. onwards, having been supplied as a standalone patch prior to this.

Patching
Note:305854.1 gives details of the latest core Web ADI, and HRMS specific ADI patches available. Please note that the HRMS Interoperability patch is in HRMS Family Pack K, and doesnt need to be applied if already on that level.

Getting Started
When HR: Enable Web ADI Integration is Y, the Web ADI Create Document program is invoked for an HR user by clicking on the Export Data icon on the toolbar of an HRMS window. There are a number of seeded integrators available for HRMS users. For instance HR HR HR HR Assignment Folder Details Assignment Details People Details People Folder Details (Assignment Folder) (Fastpath Assignment NOT Taskflow) (Enter Person) (People Folder)

To enable a user to access integrators, they need to be associated to a function which is added to the Navigator menu. The seeded integrators can be accessed by adding the submenu 'HR ADI Seeded Integrator Form Functions' to the menu. This submenu contains all the functions associated with the seeded integrators. In order to create custom integrators, access is required to certain Web ADI functions. This would normally be a task for a System Administrator. In Release 12 of E-Business Suite this is done by allocating the Desktop Integrator Responsibility. In Earlier releases, creating a specific responsibility that accesses a menu with the following functions would be the recommended approach: Seq 10 20 30 40 Prompt Create Document Define Layout Define Mapping HR Create Document Submenu Function Create Document Web ADI Layout Definition Web ADI Text Mapping HRMS Create Document

These functions are sufficient to get you started, but more may be added (discussed later) for specific tasks.Note that the HR Create Document function is the same as Create Document but filters out Integrators linked to forms and the HR Startup integrators. I.E. it allows users to run GENERAL integrators which are specific to HRMS. When creating custom integrators the HR Setup Integrator (HR_SETUP_SETUP_INTG) should be run from the Create Document function. If an attempt is made to launch the HR Create Document function without having created any general integrators, the error, 800:GENERAL% is an invalid Integrator Key will occur. It should be noted that there is a general HR Setup Integrator (GENERAL_INTG_SETUP_INTG), but it is disabled and obsolete. Please note if you create your own general integators against a custom application, you will have to change the parameters associated with the HRMS Create Document function from &bne:integrator=800:GENERAL%25 to &bne:integrator=800:GENERAL%25,999:GENERAL%25 where 999 is your custom application_id You can be more specific about the parameters passed. For example to link to a specific intergator. &bne:integrator=999:GENERAL_565_INTG To clarify, in ADI, the Create Document function is used to run your integrators. It can be run by invoking Export Data icon on the toolbar, in which case it lists all integrators associated with the form. Or it can be run directly from a menu. See above. In HRMS Only, it is used also to enable end users to create their own integrators by running specific HR Seeded integrators. It is highly recommended that these userdefined integrators are associated with your own custom application. When you create integrators, you are asked to specify the Application Short Name they are owned by. The advantage of creating them against a custom application is that you can disable them if required. You cannot disable custom integrators using the seeded HR Disable Integrator if they are created against PER. If you attempt to create an integrator against an application short name of another seeded application, for instance FND, you will get the error PER_289864_ADI_INTGR_INVAL.

Concepts
Integrator This is the definition that stores the information about the action the user wishes to perform. For example, downloading specific data to a spreadsheet for viewing or to modify and upload back to the database. For ADE users, this equated to the Style. API Application Programming Interface. This is the pl/sql interface by which data is validated and uploaded into Oracle HRMS. You would associate an api with an integrator if it was intended to either create new data in the application or update data that had been previously downloaded. See Oracle HRMS Configuring,Reporting and System Administration manual for a list of supported apis. View A view is an object by which you can query data on a table or tables. If the action you are intending to perform involves downloading data, you must associate a view with the integrator. If you are using Create style APIs, you do not require a view. You can elect to use a seeded view, for example, PER_PEOPLE_V, to use with your integrator. However, if the integrator is for updating data, then it is

recommended that you create your own views and remember to include the OBJECT_VERSION_NUMBER, and any other In/Out parameters used by your chosen API. One thing to beware of is the use of Aliases in views if you are downloading from a form. For example,if you use an alias for Applicant_Name called Starter, and then use a restrictive query in the form on Applicant Name before running the integrator in Web ADI, you will get the following error in the BNE log. BneBaseSQL.executeBneQuery: Exception while running query. Error Code: 904, Message: ORA-00904: "APPLICANT_NAME": invalid identifier The column APPLICANT_NAME has been overwritten by the alias in the definition loaded into the BNE tables. Layout This is where the user selects the columns to be displayed in the spreadsheet or Word document from the API and/or View used by the integrator. An integrator can have more than one layout defined for it. You can choose which one to use when you create your document. Mapping the mapping definition links the data source to the api columns. If no view is specified against the integrator or no text file used to load data, then no mapping is needed. When the data source is a view, the mapping is created automatically, however if a text file is being used then a mapping needs to be manually defined to associate each column in the file (source) to the relevant api parameter (target). See example c) in section, A Step by Step Guide to Creating HRMS Integrators.

Creating an Integrator
What? How? Who? What? The creation of an integrator is a task that would be performed by a System Administrator who would need to analyse the business requirement, then decide in technical terms how to achieve it. For example, if an upload or create type integrator, what api should be used? Also if not a create type integrator which view should be used to access the data in the database? If you create your own view, you can improve the quality of the document by formatting the columns in the view. Please note that there is no maintenance integrator so once the integrator has been uploaded, it is not possible to edit it if a mistake has been made. How? A detailed step by step guide on creating different integrators is included in the next section. However, in the HRMS Application, consideration has to be given to how the integrators are accessed. There are two types of Integrators, an Application Integrator and a Standalone Integrator. Application Integrators are linked to specific forms. The user uses the form in the Professional User Interface (PUI) to query data, then exports that data using the Export Data icon. The standalone integrator is created with a form name of GENERAL. This then allows the integrator to be run from a self service menu by adding the function HRMS Create Document. See section,Getting Started. You can setup a query restriction to use at runtime. Who? You control access to all HRMS Web ADI integrators using form functions. Existing form functions for seeded integrators are supplied and can be added individually to navigator menus, or in their entirety by adding the submenus, HR ADI Seeded Integrator Form Functions and HR ADI Skills Seeded Integrator Form Functions. For user-defined integrators, you must create form functions and associate them to an integrator. You can be quite flexible on how to do this. For example, one function per integrator, or by grouping several integrators to one function, if a section of your organization has access to more than one. You may wish to separate upload integrators from reporting integrators too. One integrator can also be associated with many functions by separating each function by commas. Simply add the functions to the navigator or self

service menu used by your users to give access Please note that it is possible to control access using responsibilites too. It gives a second level of security at the HR Level. Responsibility Restriction provides the 1st level of security in HR and then when Create Document page is opened to launch an integrator, the Core BNE application checks that a form function is present or the BNE profile option is set to Yes (see below) before authorising access. Responsibility Restrictions are only relevant for integators that are associated to Letters or Forms, not GENERAL integrators which are run directly from the Create Document page. To set up Responsibility Restrictions use the HR Create Integrator Responsibility Restrictions integrator. The HR Maintain Integrator Responsibility Restrictions integrator can be used to change, or remove a restriction by setting the Responsibility Short Name and Responsibility Name to blank before uploading. Please note also that once an integrator has been associated with a Responsibility then it has to be associated to all responsibilities that require access. An integrator associated with a form will be removed from the list of available integrators if Responsibility Restrictions have been enabled but not for the current responsibility. For Letter Requests an error message will be displayed APP-PER-289793: Before you can run a mail merge using this letter, your system administrator must create a Web ADI layout and integrator. The layout must match the letter name, and must be associated with the integrator which must also be attached to the LETTER group. Please also see Note:730869.1 for explanation of this error. See Oracle HRMS Web ADI Supplement for more details. It is also possible to give access to all users if there are no security implications by setting the profile option BNE Allow No Security Rule to Yes.

Running a Seeded Download Integrator

HR People Details 1. Navigate to the People -> Enter and Maintain, and run a query to return a group of records using the Find window. 2. Click on the Export Data icon on the toolbar to invoke the Create Document function. 3. Select your chosen Viewer. i.e. Excel XP, tick the Reporting checkbox, and click on Next button. 4. Choose HR People Details integrator. Remember that the list of integrators is restricted to those that have been associated with the PERWSHRG form. Click on Next button. If you get the error, You do not have permission to access this functionality", then you need to add the submenu, HR ADI Seeded Integrator Form Functions to your Navigator Menu, and try again. If you get the error, No Layouts exist for the specified integrator-Please define a layout, then you have not ticked the Reporting checkbox after selecting the Viewer. This is a download only integrator. It doesnt allow upload. 5. You will be asked to Open or Save the document to be downloaded to Excel. A Processing window will open and a Confirmation window will advise when download has completed. Click on Close button and the Excel spreadsheet will display all the rows in your original query.

Running a Seeded Upload Integrator

HR Update Salary Proposals 1. Navigate to the People -> Salary Management, and run a query to return a group of records using the View Find window. 2. Click on the Export Data icon on the toolbar to invoke the Create Document function. 3. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox, and click on Next button. 4. Choose HR Update Salary Proposals integrator. Click on Next button. Rows are downloaded to viewer as in previous section. 5. You can now manipulate the data in the spreadsheet. If changes are made, the 1st column (Upl) gets flagged for automatic upload. As a minimum you must enter values in Proposed_Salary and Change_Date fields, otherwise you will get an error in the Messages column in the spreadsheet. 6. When changes are complete, upload by going to Oracle menu on spreadsheet toolbar, and select Upload. An Upload Parameters window is presented where you can opt to upload all rows or flagged rows, and validate. Once upload is complete, requery data in Salary Management folder.

A Step by Step Guide to Creating HRMS Integrators

a) Define a Download style Integrator and Associate with a Form This example demonstrates how to create a reporting integrator to be run from the Define Payroll form. 1. From your Web ADI responsibility (See Getting Started), choose Create Document. 2. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button. 3. Choose HR Integrator Setup integrator. Click on Next button. 4. Choose default Layout, Integrator Setup. Click on Next button. 5. Choose None for Content to open empty document. Click on Next button. 6. On Document Creation Review page, Click on Create Document button. Open file and Enable Macros if prompted. A Processing window will open and a Confirmation window will advise when document has been created. 7. In the blank spreadsheet enter a value for each of the columns as follows. Remaining columns are blank for a download integrator. 8. 9. Upl 10. Metadata Type right - ignore - select List of Values from Oracle menu or

11. 12. 13. 14. 15. 16. 17.

click on mouse. Choose DOWNLOAD. Application Short Name - Choose your Application Short Name (see Getting Started) Integrator User Name - Enter a name for your integrator (eg HR Payroll Details) View Name - PAY_PAYROLLS_V2 Form Name - PAYWSDPG

18. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. At this point if you were to go to the Define Payroll form and run the integrator, you would get a No Layouts Exists message, so we must Define a Layout for the new integrator. However if you were to choose the Define Layout function at this stage and select your integrator ,you will get the error , You do not have permission to access this functionality. See Who? paragraph in Creating an Integrator section. 19. In System Administrator ,select Application-> Function. Enter a Function name and User Function Name. Commit record. Youll then need to add this function to your Web ADI menu, and also the main Navigator Menu to give access to the integrator to the end user. 20. Associate function with your new integrator, by choosing Create Document (DO NOT tick the Reporting checkbox) and choose the integrator, HR Maintain Integrator Form Functions. Default the layout and content, and then enter Application Short Name and your Integrator User Name in the window , Select Content Parameters. Click Continue button then Create Document on Review page window. When spreadsheet opens, enter a value for each of the columns as follows: 21. 22. Upl - ignore. 23. Integrator Application - Choose your Application Short Name 24. Short Name (see Getting Started) 25. Integrator User Name - Enter the name of your integrator 26. created in 7. 27. Form Function List - Enter the name of your function 28. created in 9. Separate by commas if more than one function.

29. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload 30. Now choose Define Layout function from the menu, and select your integrator, then click the Go button. You will see the informational message, No Layouts are defined for this Integrator. Press the Define Layout Button to Create a New Layout. 31. Enter a unique Layout Name and a Layout Key and press Continue 32. Select fields that you wish to see. Available fields derive from 33. 34. 1) API parameters 35. 2) View Columns

If a view column has the same name as an already included api parameter, it will be ignored. For

Upload integrators, certain fields will be identified as mandatory and will be pre-selected. If any fields always contain the same values (for example business_group_id), you can select these as Header fields, and they will appear in the Header section of the spreadsheet. These fields apply to all rows (Lines). Choose Apply to save Layout. 36. You can now Navigate to the Define Payroll form, query records, click on Export Data icon (remember to tick Reporting checkbox this time), and download the results to your spreadsheet.

b) Define a GENERAL Update style Integrator This example demonstrates how to create an integrator that will allow the download and upload of assignment details. The integrator isnt linked to any specific PUI form and can be run from the HRMS Create Document function. 1. From your Web ADI responsibility , choose Create Document. 2. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button. 3. Choose HR Integrator Setup integrator. Click on Next button. (Note: Steps 2 & 3 are reversed in R12) 4. Choose default Layout, Integrator Setup. Click on Next button. 5. Choose None for Content to open empty document. Click on Next button. 6. On Document Creation Review page, Click on Create Document button. Open file and Enable Macros if prompted. A Processing window will open and a Confirmation window will advise when document has been created. 7. In the blank spreadsheet enter a value for each of the columns as follows. 8. 9. Upl - ignore 10. Metadata Type - select List of Values from Oracle menu 11. or right click on mouse.Choose UPDATE 12. Application Short Name- Choose your Application Short Name 13. (see Getting Started) 14. Integrator User Name - Enter a name for your integrator 15. (eg Update Asg Details) 16. View Name - Create your own view, but must include 17. object_version_number from 18. per_all_assignments_f. See Getting 19. Started. 20. Form Name - GENERAL 21. API Package Name - HR_ASSIGNMENT_API 22. API Procedure Name - UPDATE_EMP_ASG_CRITERIA 23. Interface User Name - Enter a unique name 24. Interface Param List - Enter a unique name 25. API Type - select List of Values from Oracle menu 26. or right click on mouse.Choose PROCEDURE 27. API Return Type - ignore 28. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. If during upload, you get the error PER_289866_ADI_CONT_COL_FAIL , it means the view you specified above does not exist in the APPS schema. The standard for creating objects is that code objects, such as packages and views, should be created in the APPS schema and other objects should be created in the owning schema. So, custom tables should be created in the custom schema but custom views should be in the APPS schema. The Web ADI code relies on this being the case.

If you get the error, PER_289931_API_NOT_EXIST,then you have probably misspelt the package or procedure name. 29. As discussed in previous example, you now need to either create a new form function, or use an existing one for this integrator, and add it to the menu where you will be running the integrator from. 30. Associate the function with your new integrator by following step 10 and 11 in previous example. 31. Now Define Layout as described in step 12 in previous example. You will notice this time that you are presented with a list of required and optional fields. You will note that there are three required fields for this layout: 32. 33. EFFECTIVE_DATE 34. DATETRACK_UPDATE_MODE 35. ASSIGNMENT_ID These are the three Input parameters from the API which dont have defaults. In other words they are mandatory input parameters for the call to the API to be successful. The first two should be placed in the Header section, whilst the assignment_id can be a line item. You can then choose the optional fields you wish to see in the spreadsheet.. Save Layout by pressing Apply button. 36. Run integrator from HRMS Create Document. In Select Content Parameters page, you are asked to enter Session Date and an optional Extra where clause to restrict the query. N.B. The view can also be set up to restrict the data downloaded. Continue and Create Document. Additional Information Attachment for Extra Where Clause. 37. Enter Header fields, EFFECTIVE_DATE and DATETRACK_UPDATE_MODE. i.e. UPDATE or CORRECTION. Then make changes to individual lines which will flag each row for update. 38. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload If you get error, HR_7220_INVALID_PRIMARY_KEY, a possible cause could be that the column OBJECT_VERSION_NUMBER, hasnt been set to display in the layout. Or if it has, an attempt was made to change the value of the OBJECT_VERSION_NUMBER. If you are doing a datetrack correction,please ensure DATETRACK_UPDATE_MODE in Header section is set to CORRECTION and not CORRECT. If you try and change a field in the spreadsheet that is not updateable, or not an API Input Parameter, you get the error message Context Values cannot be changed. c) Define a GENERAL Create style Integrator This example demonstrates how to define an integrator that will allow the upload of new employees into Oracle HRMS from an empty spreadsheet and also using a text file.The integrator isnt linked to any specific PUI form and can be run from the HRMS Create Document function. 1. From your Web ADI responsibility , choose Create Document. 2. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button. 3. Choose HR Integrator Setup integrator. Click on Next button.

4. Choose default Layout, Integrator Setup. Click on Next button. 5. Choose None for Content to open empty document. Click on Next button. 6. On Document Creation Review page, Click on Create Document button. Open file and Enable Macros if prompted. A Processing window will open and a Confirmation window will advise when document has been created. 7. In the blank spreadsheet enter a value for each of the columns as follows: 8. 9. Upl - ignore 10. Metadata Type - select List of Values from Oracle menu 11. or right click on mouse.Choose CREATE 12. Application Short Name - Choose your Application Short Name 13. (see Getting Started) 14. Integrator User Name - Enter a name for your integrator 15. (eg Create Emp Details) 16. View Name - ignore (Views are only required for 17. download or update Integrators. Content 18. for create style apis is provided by 19. manual input to spreadsheet or text 20. file.) 21. Form Name - GENERAL 22. API Package Name - HR_EMPLOYEE_API 23. API Procedure Name - CREATE_GB_EMPLOYEE 24. Interface User Name - Enter a unique name 25. Interface Parameter List- Enter a unique name 26. API Type - select List of Values from Oracle menu 27. or right click on mouse.Choose PROCEDURE 28. API Return Type - ignore 29. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. 30. Associate with a form function which may be a newly created or existing function. See previous examples. 31. Now Define Layout.The available fields derive solely from the API as there is no view involved this time.You will notice that there are four required fields for this layout: 32. 33. HIRE_DATE 34. BUSINESS_GROUP_ID 35. LAST_NAME 36. SEX These are the four Input parameters from the API which dont have defaults. In other words they are mandatory input parameters for the call to the API to be successful. BUSINESS_GROUP_ID could be placed in the Header section if this Integrator is only concerned with one business group, whilst the others can be line items. You can then choose the optional fields you wish to see in the spreadsheet. Save Layout by pressing Apply button. 37. Run integrator from HRMS Create Document. Choose integrator and layout. Set Content to None, press Next and Create Document. A blank spreadsheet will open to allow you to enter the fields you have selected on the layout.

Upload by going to Oracle menu on spreadsheet toolbar, and select Upload Normal API valiation will be performed on each line. For instance HR_7581_ALL_MAN_EMP Employee number is required even though not mandatory in API .It is mandatory if set to manual on Business Group. Out API parameters, though they may be included in the layout for display purposes are ignored if a value is entered against them. 38. As an alternative to entering new data row by row directly into the spreadsheet, you can use a text file to pass in the data. The text file should include columns of data separated by a standard deliminator. For example,a comma. An example of the text file is shown below. The first line can be a header which would then be ignored when uploading. 39. 40. BUS_GRP,HIRE_DTE,SURNAME,SEX,EMPNO,DOB,1ST_NAME,NI_NO,TITLE 41. 5854,29-JAN-2006,O'Sullivan,M,3068,17-AUG-1970,James,YW170870C,MR 42. 5854,30-JAN-2006,Fletcher,M,3069,01-APR-1970,Andrew,YW010470C,MR Choose Define Mapping function , select your integrator, and click on Go button. Enter a unique Mapping Name and a Mapping Key, and specify the number of columns on each row of the text file. Then map the column number in the text file to its corresponding API parameter name. Note that the source column numbers have a preceding space. If the List of Values is not used, and no space in 1st position, you will get the error,Invalid Source Column Name. Run Create HR Document, choose Integrator, and select Text File for Content this time. You will be asked to specify the location of the text file, and its column delimiter. Start importing from line 2 to ignore the header if used. Press Continue and Create Document buttons.The spreadsheet open, and the text file is imported into the spreadsheet. If spurious characters appear in the spreadsheet then check the text file, and re-edit if necessary. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. Ensure you upload all rows as they will not be flagged individually for upload. d) Define a Standalone Download Integrator with an Additional Where clause This example demonstrates how to define an integrator that will allow you to run ad hoc queries in the application. In this case running query on Last Name 1. From your Web ADI responsibility , choose Create Document. 2. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button. 3. Choose HR Integrator Setup integrator. Click on Next button. 4. Choose default Layout, Integrator Setup. Click on Next button. 5. Choose None for Content to open empty document. Click on Next button. 6. On Document Creation Review page, Click on Create Document button. Open file and Enable Macros if prompted. A Processing window will open and a Confirmation window will advise when document has been created. 7. In the blank spreadsheet enter a value for each of the columns as follows. Remaining columns are blank for a download integrator.

8. 9. Upl - ignore 10. Metadata Type - select List of Values from Oracle menu 11. or right click on mouse.Choose DOWNLOAD 12. Application Short Name- Choose your Application Short Name 13. (see Getting Started) 14. Integrator User Name - Enter a name for your integrator 15. (eg AD Hoc Person Details) 16. View Name - PER_PEOPLE_V 17. Form Name - GENERAL 18. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload. 19. Associate with a form function which may be a newly created or existing function. See previous examples. 20. Define Layout. 21. Create restrictions for Standalone Query by Creating a Document using HR Create Standalone Query Integrator. This links an additional where clause to the integrator you have already created. Remember to leave Reporting checkbox unticked. Enter values for the following fields in the spreadsheet: 22. 23. Integrator Name - Name entered above 24. (e.g. AD Hoc Person Details) 25. SQL Where Clause where last_name=$PARAM$.last_name 26. 1st Parameter Name last_name 27. 1st Parameter Type Varchar2 28. 1st Parameter Prompt Last Name equals 29. 30. N.B. Add 2nd,3rd params,etc as required Upload spreadsheet 31. Run the integrator using HR Create Document function. An extra parameter line Last Name equals appears on the Download Parameters screen . Document Creation Review page then displays. Select Create Document to run the report. Additional information for the additional where clause.

Letters
Web ADI can be used to generate mail merge letters from the Request Recruitment Letter window in Oracle HRMS which associates a letter with an applicant assignment status, or Letter Request form in Oracle Learning Management which uses enrollment status. The following steps explain how to create an integrator, and a template letter, then how to generate the data source to run the mail merge. 1. The first step is to create a view to retrieve data for the letter to be downloaded to Word. The view must join with the PER_LETTER_REQUEST_LINES table, and must include the column LETTER_REQUEST_ID. For example, 2. 3. create or replace view HRV_OFFER_LETTER AS 4. select plr.letter_request_id, 5. ppf.first_name,

6. ppf.last_name 7. from per_all_people_f ppf, 8. per_all_assignments_f paf, 9. per_letter_request_lines plr 10. where 1=1 11. and ppf.person_id = paf.person_id 12. and ppf.person_id = plr.person_id 13. and paf.assignment_id=plr.assignment_id 14. and paf.assignment_status_type_id=plr.assignment_status_type_id 15. and trunc(plr.date_from) between ppf.effective_start_date and ppf.effective_end_date 16. Create a Letter Integrator as follows. N.B. Form Name must be set to LETTER. a. From your Web ADI responsibility (See Getting Started), choose Create Document. b. Select your chosen Viewer. i.e. Excel XP. DO NOT tick the Reporting checkbox because you will be uploading a new integrator definition to the database. Click on Next button. c. Choose HR Integrator Setup integrator. Click on Next button.

d. Choose default Layout, Integrator Setup. Click on Next button. e. Choose None for Content to open empty document. Click on Next button. f. On Document Creation Review page, Click on Create Document button. Open file and Enable Macros if prompted. A Processing window will open and a Confirmation window will advise when document has been created.

g. In the blank spreadsheet enter a value for each of the columns as follows. Remaining columns are blank for a download integrator. h. i. Upl - ignore j. Metadata Type - select List of Values from Oracle menu k. or right click on mouse.Choose DOWNLOAD. l. Application Short Name - Choose your Application Short Name m. (see Getting Started) n. Integrator User Name - Enter a name for your integrator o. (e.g. Offer) p. View Name - HRV_OFFER_LETTER q. Form Name - LETTER r. Upload by going to Oracle menu on spreadsheet toolbar, and select Upload 3. Navigate to Workstructures -> Recruitment Letter Type. Define a letter and link it to an Applicant Assignment Status. In this example, call the Letter ,Offer Letter (must be same as layout name), and associate it to the Offer status.Youll need to enter a concurrent program name even though it isnt used. 4. Associate with a form function which may be a newly created or existing function. See previous examples. 5. Now Define Layout, and select the fields that you wish to be included in the letter. The Layout Name must be same as the Letter Type Name in 3. i.e. Offer Letter. 6. Navigate to Recruitment -> Request Recruitment Letter. Enter Letter Name, and pick in Applicants to generate Offer letters for. Save work. This will have created rows on the table

PER_LETTER_REQUEST_LINES, and therefore the view, HRV_OFFER_LETTER, should now pick up the rows that Web ADI will download to Word. 7. In Request Recruitment Letter form, click on Export Data Icon to launch Web ADI. The form function linked to the Letter Integrator should have already been added to the PUI Navigator menu. Select Word as Viewer. Reporting checkbox should be ticked. If you get the error, Cannot Execute SQL on download, and no rows are retrieved, then its because, the letter_request_id column has been omitted from the view. Modify the view, delete layout,recreate, then try again. Once data has been downloaded into Word, save this as the data source document, for example, Offers_Data.doc. 8. Create a Template Letter using Word, and associate this with the data source file saved in 7. as follows: a. Open new Word document b. c. d. e. f. Do Tools -> Mail Merge 1 Create -> Form Letters 2 Get Data Open Data Source (and select file saved in 7.) Type your letter and use Insert Merge Field button on the toolbar to insert the data source field in the approprate place.

g. Save Template Letter document as, for example, Offers_Template.doc h. You can do the Mail Merge at this stage if required by doing Tools -> Mail Merge i. j. 3 Merge. The data will be merged into the letter and saved in a separate document. The Document will contain as many letters as are rows of data in the data source document. 9. If you now upload the Template Letter document created in 8. to the database, the Mail Merge process can be performed seamlessly when clicking on the Export Data icon in the Request Recruitment Letter form. a. Add the HRMS ADI Document Manager submenu to your Web ADI menu and give it a prompt of Document Management. b. Select Document Management , then press Upload New Document button to upload the template letter created in 8. ,Offers_Template.doc, and link it to a Category. OFFER in this case. Press Apply. If you Search on the Category Name now, all template letters linked to the category will display. Click on the document link, and the template letter you have created will display. c. Now link the template letter to the Letter Integrator and Layout.

If not already done so, Add the function WebADI Manage Document Links to your Web ADI menu, and give it a prompt of Link Document. Select Link Document option , and Web ADI Mail Merge page displays. Choose your Letter Integrator. Link it to the Layout, and a list of template documents uploaded to the database is displayed. Select the

template letter to be linked with the layout. Now whenever you create a new letter request in the Request Recruitment Letter form , and press Export Data icon, it will automatically open the template letter document in Word, and mail merge in the data source. The above scenario is designed to link in the letter generation with the Request Letter form in the PUI. However, it should be noted that you can produce standalone letters.For example,for Terminations. Simply create a GENERAL download integrator linked to a specific view to extract new termination details. Define your layout and run the integrator to save your data source in Word. Then follow steps in 8. above to do Mail Merge.

Technical
1. The main tables in ADI are as follows: BNE_CONTENTS_TL BNE_INTEGRATORS_TL BNE_INTERFACES_TL BNE_INTERFACE_COLS_TL BNE_LAYOUTS_TL BNE_LAYOUT_COLS BNE_MAPPINGS_TL Sample script to print out integrator details. Note only update integrators have apis. Reporting_Flag='N' Otherwise they are associated with the _INTFC entity 2. 3. set Pagesize 1000 4. set linesize 200 5. set termout on 6. set verify off 7. spool bne.lis 8. 9. select distinct 10. substrb(bit.application_id,1,12) APP_ID, 11. substrb(bit.user_name,1,35) INTEGRATOR_NAME, 12. bl.reporting_flag, 13. substrb(blcv.layout_code,1,35) INTEGRATOR_LAYOUT, 14. substrb(biv.user_name,1,30) ASSOC_VIEW, 15. substrb(biv.interface_name,1,20) API, 16. substrb(biv.upload_type,1,3) TYPE 17. from 18. bne_integrators_tl bit, 19. bne_layout_cols_v blcv, 20. bne_layouts_b bl, 21. bne_interfaces_vl biv 22. where 23. bit.INTEGRATOR_CODE = biv.INTEGRATOR_CODE 24. and biv.interface_code = blcv.INTERFACE_CODE 25. and bit.integrator_code=bl.integrator_code 26. and upper(bit.user_name) like upper('%&&Integrator_name%') 27. order by bl.reporting_flag 28. / 29. 30. Sample script to print out all GENERAL integrators for different applications

31. 32. set linesize 180 33. 34. SELECT application_id, 35. language, 36. source_lang, 37. INTEGRATOR_CODE, 38. SUBSTR(USER_NAME,1,30) 39. FROM BNE_INTEGRATORS_TL 40. WHERE APPLICATION_ID in (800,nnn,etc) 41. AND INTEGRATOR_CODE LIKE 'GENERAL%' 42. order by application_id 43. 44. Sample script to find integrators associated with a form function 45. 46. select security_code Integrator, 47. security_type Type, 48. security_value Function 49. from bne_security_rules 50. where application_id=800 51. and security_value = '&function_name' 52. 53. The following Viewlets are available for download from Metalink to help with the HR Integrator setup. Patch 3196431 - Disabling integrators Patch 4125542 - Creating standalone integrators Patch 3196360 - Mail merge example Patch 3196357 - Upgrading ADE to Web ADI Patch 3196355 - Download example Patch 4125537 - Creating integrators Patch 4112747 - Associating Form Functions with integrators 54. Debugging You can get a log file to help diagnose an error in Web ADI. The following profile options need to be set: BNE: Server Log Filename: Use this profile option to change the name of the Web ADI log file on the middle tier. If this profile option is not set, bne.log is used. BNE: Server Log Path: This profile option can be used to set the directory for the Web ADI log file on the applications server. If this profile option is not set, then the FND_TOP/log directory is used. BNE: Server Log Level: This profile option determines the level of detail that is recorded in the Web ADI log file. The valid values are noted below. The level of granularity and amount of information recorded to the log file increases as you move down the list. CRITICAL_ERROR: - Messages that are the result of a system failure. The integrity and reliability of the system is in doubt as a result of this error. ERROR: - Messages that are the result of an unexpected error in the system. It is possible to recover from these errors; the system may still be in a usable state. Setting the profile option to this value will include CRITICAL_ERROR messages in the log file.

WARNING: - Messages trapped by the application.These errors were handled by the application but the system administrator should be aware of them occurring. Setting the profile option to this value will include ERROR and CRITICAL_ERROR messages as well. INFORMATION: - Additional messaging is added to the log file that includes processing information. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, and ERROR log messages. This is the setting that is used by Web ADI if the profile option is not set at the site level. DETAIL: - Messages that summarize what is written to the log file. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, ERROR, and INFORMATION log messages. TRACE: - Messaging that generated detailed debugging statements. Setting the profile option to this value includes CRITICAL_ERROR, WARNING, ERROR, INFORMATION and DETAIL log messages. 55. Useful ldt files that contain seeded integrator definitions (not exhaustive) 56. 57. perzzadiint1.ldt 58. perzzadiint2.ldt 59. perzzadiint3.ldt 60. perzzadiint4.ldt 61. perzzadimap1.ldt 62. perzzadimap2.ldt 63. perzzadimap3.ldt 64. perzzadimap4.ldt 65. perzzadiparam1.ldt 66. perzzadiparam2.ldt 67. perzzadiparam3.ldt 68. perzzadiparam4.ldt 69. perzzmenuxx02195.ldt 70. Creating an Integrator in an NLS environment The script $BNE_TOP/sql/BNENLINS.sql needs to be run to populate multiple language rows on BNE_INTEGRATORS_TL table. see Note 402813.1