setup webadi

1

April 2006

How to Spin Web/ADI to How to Spin Web/ADI to Update your HR DataUpdate your HR Data

Bill StrattonDheeraj Sharma

2

AgendaAgenda

• Introduction• Web ADI Prerequisites• Web ADI Terminology• Salary Management Integrator• Custom Update Integrator• Questions and Answers

3

Introduction Introduction -- XcelicorXcelicor

• Founded 1997• Focused exclusively on Oracle HRMS• People who “Excel” at their “Core”

competency of Oracle HRMS

4

Web ADIWeb ADI

• Replaces WEB ADE• Requires no client software• Entirely web-based• Has download and upload capabilities• Oracle stated direction

Web ADI is now the Oracle supported way to download and upload data from Oracle applications to your desktop. It replaces the old WEB ADE, which required special client software to be installed on the target PC. Web ADI is entirely web-based and does not require any special client software beforehand.

5

Web ADI PrerequisitesWeb ADI Prerequisites

• Must set profile option HR: Enable Web ADI Integration to Yes

• Internet Security Options – Download Unsigned ActiveX controls set to at least “Prompt”

• Excel – Tools – Macro – Security – Trusted Publishers – Trust Access to Visual Basic Project Radio button checked

• Menu HR ADI Seeded Integrator Form Functions to initial signon menu for responsibility

There are a number of task that must be performed before you try downloading or uploading via Web ADI.

First, the System Administrator must set the System Profile option HR: Enable Web ADI Integration to Yes.

On the client desktop, set the Internet Security Options – Download Unsigned ActiveX controls to at least “Prompt”

Within Excel, navigate to Tools – Macro – Security – Trusted Publishers. Check the Trust Access to Visual Basic Project radio box.

The responsibility that the user will use should have the menu HR ADI Seeded Integrator Form Functions included in their initial signon menu.

6

Web ADI TerminologyWeb ADI Terminology

• Integrator• Layout• Mapping

Integrator is the main object in Web ADI. It is used to contain all of the relevant information concerning a particular download or upload. It controls whether you can only download, only upload or both. You can control who has access to an integrator by a responsibility.

The Layout defines the columns that will appear on the spreadsheet. You can have more than one layout associated with an integrator.

Mappings are used when you are bringing in data from a legacy flat file into Oracle. The mapping definition will map the columns on the legacy file to the view that will be used to upload the data into the application tables.

7

Web ADI Web ADI ““Out of the BoxOut of the Box””

• People – Salary Management• View – List – People Folder• View – List – Assignment Folder

Oracle delivers integrators right out of the box. Assuming that the target responsibility has these seeded integrator functions included on the initial logon menu, you can begin using them without loading any other special software.

We will be showing the Salary Management integrator next.

8

Salary Management IntegratorSalary Management Integrator

• Used to do Mass Salary Updates• Navigation path: People – Salary

Management• Using Folder Tools, added Organization• Sorted Folder results by Organization

The salary management integrator is one of the seeded integrators that is tied directly to the Salary Management screen. You first navigate to the Salary Management screen. I modified the folder, using the standard folder tools, to include Organization in the folder. I ran a blind query and then sorted the results by organization. The next screen will show the results of this query.

9

Here you can see the results of my query. We will focus on my name here.

The next step is to start the Web ADI integrator by click on the Export icon button.

10

The system will respond with the screen above. We will leave the reporting box unchecked, since we will be changing the downloaded data and uploading it back to Oracle.

Click on the Next button to go to the next step. (Notice the train above that tracks our progress).

11

Eventually, the system will respond with this dialogue. Click on the Open button to navigate to the next screen.

12

The next two screens will show the data downloaded into the spreadsheet. As you change (or add data) to this screen, the Upd indicator will appear (the little flag icon). Here I have added the change date.

The next screen will actually show the salary change.

13

I have scrolled to the right and put in the proposed salary and change reason. Note that I had to use the actual code of the change reason, since the API that is being used requires the code.

14

The next step is to start the upload process. It is located on the menu taskbar under Oracle as shown above.

15

You can control which records actually get uploaded by making the appropriate selection here.

16

Since I selected to send only the indicated rows, it only sent up my record. Note the little smiley face. If the processed detected an error, it would be listed here.

17

Here is the uploaded record in the salary proposal screen. Note that it is still unapproved, so you will need to use the salary management screen again to approve the salary.

18

OK, Lets Create our own OK, Lets Create our own IntegratorIntegrator

• Will use a custom HR data view that de-normalizes Person, Address, Assignment and Salary tables

• Will use HR Assignment API (sort of)• Must include Oracle Web ADI Menu to

responsibility• Actual Business Case

– Implementing Daily Business Intelligence– Several regions missing Supervisors– Need mass update capability to load Supervisors

So lets create an integrator from scratch. This particular integrator will not be attached to any screen. As you will see later, we will initiate this screen from the Web ADI menu item called Create Document.

This is an actual business solution we are experimenting with at a current client. We first created a denormalized view that joined the person, address, assignment and salary tables.

We will use a version of the standard HR Assignment API. I will discuss this further shortly.

We need the Oracle Web ADI Menu on our initial logon menu, so that we can create this integrator.

We are implementing Daily Business Intelligence and not all of our regions populated the Supervisor field on the Assignment screen during implementation. DBI controls its displays based on the supervisor hierarchy, so we needed this completed for everyone before we can roll this out. So our integrator will download everyone that does not have a supervisor to a spreadsheet so that we can add this information in and upload it back to Oracle.

19

API IssuesAPI Issues

• In order to update, you must first download

• What about all of those IDs?– Person ID– Assignment ID

• What is a Wrapper?• Make friends with your IT staff

One of the requirements to upload data to Oracle applications via Web ADI, is that you must use an API (or a Application Programming Interface). There are some issues we need to discuss concerning APIs.

Since we are updating existing Assignment records (as opposed to creating all new assignments), we must first download the existing version of the assignment, make the change and then upload.

The standard Oracle supported APIs all use record IDs, instead of the more user friendly fields we see on the screen. In particular for our example, we need the send the API, the person id of the supervisor and the assignment id of the employee. Since users will not know these ids, we must come up with a better plan.

Our solution was to write a PL/SQL function that would take the numbers we would normally know, like the employee number of the supervisor and the assignment number of the employee, look up the ids and then call the API. This special code is called a Wrapper and will make our process easier.

Obviously, this is a task for a technical resource, so make some friends with your IT staff.

20

Supervisor WrapperSupervisor Wrapper

• Uses HR Assignment API• Four Input Parameters

– Effective Date– Date Track Mode– Assignment Number of Employee– Employee Number of Supervisor

• Finds all necessary IDs• Handles Supervisor Hire Date Issue

So, we created our own custom wrapper for this process.

It uses the standard HR Assignment API, so that we are using Oracle supported functionality when updating our assignment records.

Our special function has four parameters. They are the effective date of the change, the date track mode (whether it is an update or a correction), the assignment number of the employee and the employee number of the supervisor. The function uses these parameters to find the necessary assignment and person ids. It also handles the issue when the supervisor’s hire date is after the employee’s current assignment effective date. If it is, then it will change the date track mode to update and use the supervisor’s hire date as the new assignment effective date. If not, then the date track mode will stay as a correction.

21

Ok lets get started. We will actually use Web ADI to create our integrator. The first step is to select the Create Document menu item from the Web ADI Menu.

22

I have taken these screen shots from the client machine, so I have blanked out the URL stuff to protect the innocent.

The first screen is used to select which viewer we will use to create our integrator. We are going to use Excel. Also, the Reporting box is unchecked, since we are going to upload our integrator definition back up into the database.

23

We are actually using a seeded integrator to create our custom integrator, sort of a bootstrap like process. Here we are selecting the seeded HR Integrator Setup integrator.

24

We are also using the supplied layout for the integrator definition.

25

Content determines what gets included on the spreadsheet when it is downloaded. Since we want to start with a blank spreadsheet, we select None for content.

26

Here is our last chance to fix any of our choices. Once we select Create Document, it will create a blank spreadsheet for us to use to define our new integrator.

27

After the blank spreadsheet is created and downloaded, Excel will start up and display the columns we need to populate to define our Supervisor update integrator.

28

The first column describes what this integrator can do. We can either create new records, download existing records, or download and update existing records. Since we want to update existing assignment records, we will select UPDATE.

29

Next, we need to select an application code. Best practices dictate that you should put all custom code into your own custom application code, as we have done here. You can use the Oracle menu option to get a list of valid values.

30

Next, we need to name our integrator. This is the name that will appear in the pick list when the user starts their own “Create Document” session.

31

Next, we need to specify want view to use in order to retrieve our desired records to update. As I stated before, we created a custom view that joins the person, address, assignment and salary record together. You could also use one of the Oracle supplied views. You will need to work with your new friends in the IT department to help you with this.

32

As you saw in the Salary Management example, you can attach an integrator to an existing Oracle form. In our example, we are not attaching this to any form, so we select GENERAL.

33

Our wrapper that we created is included in a package we called XCEL_UTILITY. We need to tell Web ADI this information as well as the actual procedure name in the next column. You need to get this information from your technical folks.

34

Here is the name of the actual procedure we created that will take our inputs and call the HR Assignment API.

35

Once we have completed this spreadsheet, we can start the Upload process from the Oracle menu taskbar.

36

Similar to the Salary Management example, we are going to upload just the flagged records. You could create several integrators with one pass.

37

Function SecurityFunction Security

• Must create a function to secure Integrator

• System Administrator – Application –Function

• Attach function to Menu• Attach function to Integrator

We would eventually get a conformation that the integrator was successfully added.

Now we must say who is allowed to use this integrator. Oracle uses the menu function process to secure integrators. Therefore, we must create a menu function and attach it the menus that are allowed to use it. Then we attach the function to the integrator. This is a System Administrator process.

38

Here is a picture of the function definition. We are really just creating a placeholder, so that we can add this to a menu.

39

Here is the next tab in the process.

40

Here I am adding this newly created function to an initial signon menu.

41

Now we need to attach this function to our newly created integrator. Once again, we are going to use Web ADI to do this for us. Select Create Document to start this process.

42

We will use Excel again to attach the function to the integrator.

43

We will use the seeded HR Maintain Integrator Form Function Associations integrator to perform our desired task.

44

This will download all of the integrators associated with our custom application. You could supply just the desired integrator (the one we just created) in the Integrator User name field if you wish.

45

Here is the form function template. We just need to add the name of our function on the line for our newly created integrator.

46

Now we are ready to create the layout of the spreadsheet that will be used to update the supervisors on the employee assignment screen. Again, we use Web ADI to perform our definition. Select Define Layout from the Web ADI Menu.

47

First select the integrator that you want to create the layout for. Here we are selecting our newly created integrator.

48

The first four columns are the parameters to our wrapper. You can see where I am putting the effective date and date track mode options in the header of the spreadsheet, but the assignment number and supervisor employee numbers will be down in the line items. I then go and check the fields from our view that I want displayed on the spreadsheet.

49

Here are the other fields I want displayed. Remember our wrapper is only going to update the supervisor field, so even if the user changes any of these fields, the wrapper will just ignore the change. I only included these fields to assist the user.

50

Stand Alone QueryStand Alone Query

• Attaches a query to the Integrator

Once the layout is created, we now want to create a query so that we do not download every assignment when we launch our integrator.

51

Again, we use Web ADI to create this query. Select the Create Document item.

52

Select our viewer again.

53

Now we are going to use the seeded integrator HR Create Standalone Query to create our query.

54

Here we are creating our Where clause. Once again, use your new friends in IT to assist you. Our query is going to prompt the user for a department name. This will restrict the download to just employees who are in this department. Notice the weird name we have to give the parameter. This tells the query to prompt for the desired name.

55

This column describes the parameter name.

56

This column describes the type of data that will go into the parameter. Here we are saying that the parameter will contain character data (the name of the desired department).

57

This is the prompt the user will see when the integrator asks for the department name.

58

Lets give it a tryLets give it a try

• Upload the Stand Alone Query• Use the Create Document

Once again, we upload the query and we should now be ready to give it a try. We will use the familiar Create Document, but now we will use our new integrator.

59

We select our viewer again. This means that the selected assignment records will eventually show up in Excel.

60

Here is our integrator.

61

The mapping is not used for our example, since we are downloading the data that is being updated. Mappings are used to create new records from an existing text file or spreadsheet.

Here we enter a session date and see how our prompt show up. We must enter the department name as it appears on the Assignment screen.

You can create a drop down box of valid department names, but that takes some additional technical setups that are outside of the scope of this presentation.

62

Here is a partial list of the downloaded data. Since I am using live client data here, I blanked out some of the names. Notice that I am using my test employee here. I entered the employee number of the desired supervisor and the assignment number of the employee.

63

When I uploaded the spreadsheet, my new supervisor now shows up.

64

Some Final NotesSome Final Notes

• Use Secured Views when interacting with Security Profiles

• Oracle HRMS Web ADI Implementation and Configuration Supplement (228527.1)

• Patch 4125542 for viewlets“PROVIDE VIEWLET FOR CREATING STANDALONE INTEGRATORS”

Some final thoughts.

Make sure you use secured views with your integrator. This will keep users from seeing employees that they are not supposed to see. Our custom view, did use the secured views as a base.

A good reference document is shown above. I used this document extensively to teach myself Web ADI.

There are also some interesting viewlets you can watch that demos the integrator creation process. Download the patch number above and give them a try.

65

Questions?Questions?

Thanks for your attention!!

Bill StrattonDheeraj Sharma

Xcelicorbstratton@xcelicor.comdsharma@xcelicor.com