ORACLE USER MANAGEMENT Developer’s Guide

Author: Oracle User Management Development

Creation Date: 29-Dec-06

Last Updated: 31-Jan-07

Version: R12, v. 1.0

Status: Published

Copyright © 2007 Oracle Corporation All Rights Reserved

1. Document Control

1.1 Change Record

Date Author Version Change Reference

12/29/2006 Oracle User Management Development

1.0 Created R12 version.

1/31/07 Oracle User Management Documentation

1.0 Published document.

Page 2 of 31

Contents

1. Document Control..................................................................................................2

1.1 Change Record........................................................................................................................ 2

2. Introduction............................................................................................................1

3. Registration Processes ...........................................................................................2

3.1 Overview................................................................................................................................. 2

4. Developing Registration Processes 1-2-3 .............................................................4

4.1 Development Steps: Overview................................................................................................ 4

4.2 Registration Architecture ........................................................................................................ 5

4.3 Schema Dependencies........................................................................................................... 10 People 11 External Organizations ............................................................................................................ 11 External Organization Relationships ....................................................................................... 11 Internal Organizations ............................................................................................................. 11 User Accounts ......................................................................................................................... 11 Roles 12 Responsibilities........................................................................................................................ 12

4.4 Step 1: Develop Registration UI’s ........................................................................................ 12 Coding Guidelines ................................................................................................................... 12

4.5 Step 2: Subscribing to Business Events & Handling Registration Data................................ 16 Overview & General Guidelines ............................................................................................. 16

4.6 Step 3: Define Notification Workflows ................................................................................ 18

4.7 Step 4: Define Approval Routing Rules................................................................................ 21 Overview ................................................................................................................................. 21 Routing Approvals based on Registration Data....................................................................... 21

4.8 Step 5: Extracting Seed Data................................................................................................. 22

5. User Name Policy – Administration and Customization.......................................23

User Name policy ........................................................................................................................... 23 Overview ................................................................................................................................. 23 Administration - Configuring the User Name Policy .............................................................. 25 Customization – Creating a new user name policy.................................................................. 27

6. Appendix A: Java Doc .............................................................................................31

Page 3 of 31

2. Introduction This developers guide includes specific information and guidelines required for design and development of registration processes integrated with Oracle User Management. The document also includes detailed information on the Oracle User Management registration architecture/infrastructure and the processing that goes on behind the scenes.

Disclaimer: This is a living document and provided as is, coding standards and guidelines described in this document may change without prior notice; any such changes may require modifications to your code.

Page 1 of 31

3. Registration Processes

3.1 Overview

Registration Processes allow organizations to streamline account provisioning and access control assignment through predetermined flows. Registration Processes can be defined to support each organization’s unique business requirements, and allows you to:

• Capture information from the requester through UI’s built specifically to handle each type of request.

• Define whether approval is required and by who, based on:

o Information provided by the requester

o The identity of the requester

o The server the request originated from

o Manager chain

o Any other criteria or information available in the Oracle Applications database

• Define specific email notifications (identity verification, approval, confirmation, rejection) for each type of request

• Keep information entered by the requester in a temporary storage until the request is approved (avoids garbage data in your production tables)

• Define specialized business logic to handle the data for each type of request

• Define what set of users are allowed request access to a given part of the system (who can request each role).

Oracle User Management supports four types of registration processes:

• Self Service Account Requests are typically invoked from a public webpage where a "Register Here" link has been embedded. Once a person has completed the registration process, they should at a minimum have a TCA person party record, a user account, as well as one or more roles that give the requester access to a restricted part of the website they signed up from. An online store is a typical example where this type of registration process is useful; customers need to register before being able to make a purchase.

• Administrator Assisted Account Creation is similar in nature to registration processes defined to support Self Service Account Requests. The difference is that security administrators register new people and/or user accounts on behalf of the end user. A typical usage scenario: Your company has a business relationship with some other organization. People from the external organization should be given access to a limited set / parts of the applications you have deployed. Since employment changes on a day-to-day basis at every organization, you decide to designate a person from the external organization as the local security administrator. This person should not only be allowed to assign and revoke a subset of roles and approve self service requests, but also be able to maintain and create user accounts as well as register new people for their organization.

Page 2 of 31

The latter two can be accomplished by granting a set of local administrators access to the Administrator Assisted Account Creation registration processes defined for this specific purpose.

• Self Service Requests for Additional Access. Once a person has a user account they may need access to additional parts of the system. Access is granted to users by assigning one or more roles, this can be initiated by:

o End users request access through the Access Request Tool (ART). ART is available to users through the global “Preferences” menu after login. Users can only request roles they are eligible for, which is typically determined by what other roles and groups (in the workflow directory) the user is already a member of.

• Administrator Assisted Additional Access. Once a person has a user account they may need access to additional parts of the system. Access is granted to users by assigning one or more roles, this can be initiated by:

o Security Administrators, including local administrators, assign roles to the users they manage.

So when and why would you define a registration process?

• Should existing users be able to request a given role through the Access Request Tool? • Should users receive notifications when a role is assigned to them? • Do you require certain types of requests to be approved? • Does the application(s) that your roles/responsibilities provide access to require specific

information to be known about the end user, or do they currently require manual setup for each user - such as profile options or other user level settings?

• Do you require self-service registration functionality? • Do you want to enforce how a set of local security administrators can register new users,

and ensure that all information is captured in one seamless flow requiring no additional manual setup steps?

If the answer to any of the above questions is yes, then registration processes are for you.

Page 3 of 31

4. Developing Registration Processes 1-2-3

4.1 Development Steps: Overview

As will be discussed in detail in the Schema Dependencies section, all user accounts (except system accounts) must be linked to a person party defined in TCA. This means your account provisioning registration processes at an absolute minimum must capture personal information such as name and email address, and later on have a person party created in TCA with this information (or alternatively, have your registration process identify an existing person party in the system).

Some applications require the user not only to be granted the necessary permissions to access the application (permissions are granted through roles), but also require user specific settings such as profile options, resource group membership, or other information to be defined. In the past, getting this information into the system has typically been done through manual setups, which is both an error prone and labor-intensive process. The goal is for each registration process to cover all the setup steps required. When defining your registration processes you have a few options for how to get this information:

• Let the requester (whether an administrator or the end user) enter some or all the information up front in the registration UI

• For self-service flows, have the approver enter any information (in the approval notification response) that the requester should not be able to enter or have control over.

• Have your code derive the information based on any other data entered throughout the registration flow.

If the current setups required are simply too complicated to automate into one flow, automate what you can and list the additional manual steps required in the approval notifications for your registration process. This will save the approver / administrator a lot of time and headache, since the steps are different for each type of request.

Developing a registration process can be as simple as defining some metadata, or as involved as defining custom user interfaces and processing logic. The following outlines the most complex case. Each step is optional as you may be able to use the predefined components provided by Oracle User Management, all depending on your requirements.

1. Ensure your security setups* are complete (roles, role categories, role inheritance hierarchies, responsibilities, menus, permission sets, permissions, grants, data security policies).

2. Build the registration UI to capture required information from the requester, whether an administrator or end user [UI’s are optional for Additional Access registration processes]

3. Define business event and subscriptions to write the registration data to the destination schemas once the request has been approved.

4. Create a notification workflow by copying one of the pre-seeded workflows provided by Oracle User Management. Customize the notifications in your copy as appropriate.

5. Define a set of approval routing rules in Oracle Approval Management,

6. Create the registration process metadata* definition with the components defined in the previous steps.

Page 4 of 31

7. Extract the metadata using loaders

8. In your target environment, expose the self-service registration flows on login page* and define custom registration parameters for each server.

*Please refer to the Oracle User Management section of the Oracle Applications System Administrators Guide – Security for more information.

The next sections will go through the above steps above in more detail.

4.2 Registration Architecture

In order to build registration processes you also need some general understanding of the Oracle User Management registration infrastructure and the processing that goes on behind the scenes.

The diagram below illustrates the major components and steps in a self-service account registration flow (requests for additional access are using the exact same infrastructure, some parts like creating person parties and activating user accounts are obviously not required).

High Level Flow: Self Service Account Request

Enter InfoRegister SubmitRequest

RaiseBusiness

Event

InvokeRegistration Engine

ReserveUser Name

Verify Identityvia Email

CreatePerson Party

ActivateUser Account

AssignRoles

EmailTo Approver(s)

Approved!

ConfirmationEmail

WriteRegistration Data

EventObject

EventObject

EventObject

EventObject

EventObject

EventObject

EventObject

EventObject

EventObject

EventObject

Confirmed!

The following is a detailed description of the above flow and is provided so that developers understand the details of the entire process. At first this information may seem overwhelming and complicated, but the majority of the code is implemented by Oracle User Management and handled automatically for you. Developers building registration processes only need to code registration UI’s, copy and customize notification workflows, define approval routing rules, and write some simple code to handle the registration data once the request has been approved. Coding guidelines for each will be described in subsequent sections of this document.

1. A person clicks on the “Register Here” link on the login page. The login page has been enhanced with the introduction of Oracle User Management to support a couple of nifty features:

a. The registration link can point to a different registration process for each server/midtier the login page is accessible from.

Page 5 of 31

b. Each registration link (URL) can include server / deployment specific registration parameters and values that are not known at design time. These parameter values are accessible to your code throughout the entire registration flow. Consider the case where all registration requests originating from the United States should be routed to the US Administrator, and requests originating from the United Kingdom be routed to the UK Administrator. In this case the approval routing engine must know from where the request originated. You can achieve this by deploying two midtier servers (to service requests from the US and the UK respectively) and have the registration URL for each include a registration parameter, defined as a name-value pair, such as ORIG_COUNTRY=<country code> (see the Oracle User Management section of the Oracle Application System Administrators Guide – Security for details on how to enable and setup midtier specific registration links and registration parameter name-value pairs on the login page). Assuming the registration UI has been coded in accordance to the standards defined in this document, the ORIG_COUNTRY parameter value can now be used as a condition in your approval routing metadata (or anywhere else throughout the registration process), see the Approval Routing Rules section for details.

2. After clicking the registration link on the login page, the user is directed to the registration process specified for the originating midtier/server, and:

a. The first page in the registration flow instantiates a BC4J Application Module and reads the deployment / midtier specific registration parameters (name-value pairs) that were part of the registration URL on the login page. These values, in addition to the registration process code / unique identifier (REG_SERVICE_CODE), are contained in the UMXRegParams parameter in the HTTP request object NOTE: The UMXRegParams HTTP parameter is also used to carry context in registration processes defined for Additional Access and Administrator Assisted Account Creation. Instead of the login page as the starting point, the request would be initiated from Access Request Tool or the Oracle User Management User Administration UI. In these flows, registration parameters such as: REQUESTED_BY_USER_ID, REQUESTED_FOR_USER_ID, and others would be included in UMXRegParams. See the Subscribing to Business Events & Handling Registration Data section for information on what registration parameters are populated in each scenario. NOTE: Developers should not try to decipher the information held in the UMXRegParams parameter as the structure and content is for internal use only. Once the RegistrationBean (see next step) has been instantiated, all the information is accessible through properties on this object.

b. A RegistrationBean is instantiated (see the Registration UI’s section of this document), and the registration parameters from UMXRegParams are set as property values on this object.

c. The RegistrationBean queries up the registration process metadata from the database (based on the process code), and populates the corresponding properties of the bean with this information.

d. The RegistrationBean is stored in the BC4J transaction cache, and hence available to all the pages in the registration flow.

e. A BC4J commit listener is registered for the current transaction.

f. The registration UI is displayed to the end user; the requester enters the information required, and submits the request.

Page 6 of 31

At the end of each page in the flow, all information entered is validated through the standard mechanism provided by the BC4J infrastructure through View Objects and Entity Objects. Once the information entered by the requester has been validated it is written to the RegistrationBean (instead of the database and target schema) through the insertRow methods on the Entity Objects in the registration flow. The RegistrationBean is now acting as an information store, holding all the registration data in temporary storage until the request is approved. This avoids having your production tables be populated with information until it is deemed that the information is correct and the request is valid and approved.

g. The last page of the registration flow issues a commit call on the transaction from the processFormRequest method of this page.

h. Any final validation is now executed, and under normal circumstances the submitted information would be committed to the destination tables in the database. Before the actual database commit happens, the BC4J framework invokes the commit listener registered in step e) above. The commit listener invokes some code provided by Oracle User Management, which:

i. Instantiates an event object, as provided by the Oracle Workflow Business Event system.

ii. Retrieves the RegistrationBean from the transaction cache.

iii. Generates a unique request id to represent the request. The request id will be used not only as the confirmation number displayed to the requester, but also to uniquely identify the ITEM_KEY of the Oracle User Management Registration Engine workflow process (ITEM_TYPE = UMXREGWF) that will handle the request.

iv. Reads all the registration data stored in the RegistrationBean as name-value pairs.

v. Sets the name-value pairs into the event object instantiated in step i) above.

vi. Raises a special business event that has the Oracle User Management Registration Engine workflow process defined as a synchronous listener. The event object is set at the payload of the business event, and has now taken over the responsibility to act as the information store of registration data (from the RegistrationBean).

vii. Any predefined workflow attributes in the Oracle User Management Registration Engine workflow which have the exact same name as the name-value pairs stored in the event object, are automatically populated with the corresponding values.

3. The Oracle User Management registration engine is now responsible for processing the registration request. Any activities that can be performed synchronously, up to the first blocking / asynchronous activity (email notifications that require a response) will be executed immediately.

a. If an error occurs while executing any of the synchronous activities:

i. The error is propagated back to the commit listener

ii. An exception is thrown with the error stack from workflow

Page 7 of 31

iii. The transaction is rolled back

iv. The error is displayed to the requester

b. If there are no errors and neither identity verification nor approval is required, all the activities and steps performed by the Oracle User Management registration engine are executed synchronously. Once the confirmation email has been sent to the requester, control is returned back to the commit listener, and the status in the RegistrationBean is updated to APPROVED. BC4J then issues the actual database commit, which ensures that the registration process state is stored in the database. The next line of code after the commit call (in the processFormRequest method of the last page in the registration UI) can interrogate the status in the RegistrationBean and forward to a confirmation page.

c. If identity verification is required, all the activities and steps up to that point are executed synchronously. The processing of the registration request proceeds asynchronously as soon as the first blocking activity is encountered, but before that control is handed back to the commit listener which sets the status in the RegistrationBean to VERIFYING. BC4J then issues the actual database commit, which ensures that the registration process state is stored in the database. The next line of code after the commit call (in the processFormRequest method of the last page in the registration UI) can interrogate the status in the RegistrationBean and forward to a confirmation page.

d. Similarly, if identity verification is disabled but the request requires approval, all the activities and steps up to the approval activities are executed synchronously. The processing of the registration request proceeds asynchronously as soon as the first blocking activity is encountered, but before that control is handed back to the commit listener, which sets the status in the RegistrationBean to PENDING. BC4J then issues the actual database commit, which ensures that the registration process state is stored in the database. The next line of code after the commit call (in the processFormRequest method of the last page in the registration UI) can interrogate the status in the RegistrationBean and forward to a confirmation page.

4. The first thing the Oracle User Management registration engine does is raise a business event (either oracle.apps.fnd.umx.rolerequested or oracle.apps.fnd.umx.accountrequested) to notify any subscribers that a request has been submitted. The event object with all the registration data is set as the payload of the event.

Note: Only generic usage like auditing applications should be listening to this event.

5. A new password is randomly generated if the requester did not enter a password, the password is then stored in the PASSWORD parameter of the event object.

6. The requested user name (from the REQUESTED_USERNAME parameter of the event object) is now reserved in the Oracle Applications database. This ensures that no one else can request this user name while the request is being processed.

7. If identity verification is required for the current request / registration process, the notification business event (as defined in the registration process metadata) is raised with the event object as payload, and:

a. The notification workflow (defined as a subscriber to the notification business event) is invoked. Any predefined workflow attributes in this workflow, which have the exact same name as the name-value pairs stored in the event object, are automatically populated with the corresponding values.

Page 8 of 31

b. An email notification is sent out to the email address submitted as part of the request (defined in the EMAIL_ADDRESS parameter of the event object). This email notification can include any of the data stored in the event object.

c. If a response / confirmation has not been received within a predetermined amount of time:

i. Control is returned back to the Oracle User Management registration engine, which rejects the request.

ii. The previously reserved user name is released, which means it is now available to anyone else.

iii. The registration request is aborted.

d. If a response / confirmation on the other hand is received:

i. Any changed or new registration data provided by the recipient in the response are set as name-value pairs in the event object

ii. Control is returned back to the Oracle User Management registration engine, processing continues.

8. The approval routing rules (if any) defined for the current registration process are interrogated by invoking the approval routing engine provided by Oracle Approval Management. If the request requires approval, the notification business event is raised with the event object as payload.

a. The notification workflow (defined as a subscriber to the notification business event) is now invoked again, but this time to send out approval notifications. Any predefined workflow attributes in this workflow, which have the exact same name as the name-value pairs stored in the event object, are automatically populated with the corresponding values.

b. An email notification is sent out to the approver (as specified by the approval routing engine). This email notification can include any of the data stored in the event object.

c. If the request is rejected:

i. Control is returned back to the Oracle User Management registration engine.

ii. The previously reserved user name is released, which means it is now available to anyone else.

iii. The notification business event is raised for the final time with the event object as payload:

1. The notification workflow is invoked.

2. A rejection email is sent to the email address provided by the requester.

d. If the request is approved:

i. Any changed or new data provided by the approver is set in the event object.

Page 9 of 31

ii. The approval routing engine is invoked again to determine whether anyone else needs to approve the request.

iii. A new email notification is sent to the next approver (and so on)

iv. Once final approval has been received, control is returned back to the Oracle User Management registration engine, and processing continues as defined below.

9. If the request represents an account provisioning registration process, and if a business logic event has been defined for the current registration process, it will be invoked with the context of “BEFORE ACCOUNT ACTIVATION” in the event attribute UMX_CUSTOM_EVENT_CONTEXT with the event object as payload, and:

a. The code registered as a subscription to the business event (by the owner of the registration process) is invoked.

b. The subscription creates a person party in TCA (and writes any additional information related to the person party into the destination schemas).

c. The subscription stores the person party id in the PERSON_PARTY_ID name-value pair of the event object.

10. The user account is activated and linked with the person party from the previous step.

11. If the request represents an account provisioning registration process, and if a business logic event has been defined for the current registration process, it will be invoked with the context of “AFTER ACCOUNT ACTIVATION” in the event attribute UMX_CUSTOM_EVENT_CONTEXT. The owner of the registration process must register a subscription to this event if any of the registration data require foreign keys to the user account (such as profile options), and ensure that the information is written into the target schemas.

12. The roles (if any) defined in the registration process metadata are assigned to the user.

13. The oracle.apps.fnd.umx.requestapproved business event is raised with the event object as payload to indicate that the request has been approved. This event can be subscribed by generic applications like auditing to keep track of registration requests. NOTE: If your registration process is defined for additional access, the business logic event in steps 9 and 11 above are not raised. You must therefore write any registration data to the target schema by subscribing to the business logic event with the context of “ROLE APPROVED”.

14. The notification business event is raised for the final time with the event object as payload:

a. The notification workflow is invoked.

b. A confirmation email with user name and password is sent to the email address provided by the requester.

4.3 Schema Dependencies

This section describes some of the schema components that Oracle User Management depends on. Building new registration processes requires detailed knowledge of the schemas and database objects described here, as well as the corresponding API’s that must be used to maintain the data

Page 10 of 31

in each table. Please refer to the product specific documentation / API guides for more information.

People

The Oracle Applications security system (and many other modules in the eBusiness Suite) has from 11.5.10 and onwards standardized on the Trading Community Architecture (TCA) as the central repository / storage place for personal information. Each person is defined as a party of type “Person” (person party) in the HZ_PARTIES table, and is uniquely identified by the PARTY_ID primary key column. TCA also supports storing phone numbers, addresses, and many other things.

NOTE: TCA is not the source of truth of personal information for all applications in the eBusiness Suite. As an example, applications such as Oracle Human Resources mainly use their own tables for storing personal information, but also has code to denormalize the information into TCA from the source schema - some exceptions exists (most person records in the Human Resource application include a PARTY_ID foreign key to the denormalized person party in TCA). Please refer to the application specific product documentation for more information.

External Organizations

External organizations are those your company has some sort of business relationship with, whether they are a customer, partner, supplier, or something else. These organizations are stored in TCA as parties of type “Organization” (organization parties) in the HZ_PARTIES table, and are uniquely identified by a PARTY_ID.

External Organization Relationships

A person employed by an external organization would be defined as such by having a relationship record (typically of type “EMPLOYEE_OF”) in the HZ_RELATIONSHIPS table. Oracle User Management supports searching on users by their organization relationship, based on the relationship types defined in the PARTY_REL_GRP_CONTACTS relationship type group. Please refer to the TCA documentation for more information.

Internal Organizations

Internal organizations such as Business Groups, Cost Centers etc are stored in the Oracle Human Resources product schema. Oracle User Management has no dependency on these tables as of 11.5.10, but will leverage some of this data in an upcoming release.

User Accounts

In order to access the system each person must have a user account. User Accounts are stored in the FND_USER table, and are uniquely identified by the USER_ID primary key. Each user account must be linked to a person through the PERSON_PARTY_ID foreign key column in FND_USER, with the exception of system accounts (such as the guest account).

NOTE: The FND_USER table includes three additional foreign key columns, EMPLOYEE_ID, CUSTOMER_ID, and SUPPLIER_ID. Usage of these columns is discouraged, as they will be made obsolete (now replaced by PERSON_PARTY_ID) in some future release. Defaulting logic (to maintain backwards compatibility) exists, as some applications still require these columns to be populated.

Each record in the FND_USER table must specify not only a user name, but also an email address. The email address is required for sending email notifications (through workflow) to a user. The

Page 11 of 31

self-service “Forgot Password” functionality included in Oracle User Management is one of many examples that rely on this information being defined and correct.

NOTE: Email addresses may be defined in several product specific tables, including but not limited to TCA. Organizations must ensure that a person’s primary email address (from the source tables), is also set for the user account.

Roles

Roles are assigned to users in order to grant them access to parts of the system; this can include access to a given set of application pages/forms as well as a restricted set of data within those pages.

Roles are stored in the workflow directory, identified by the NAME primary key column, and accessible through the WF_ROLES view. Role assignment is also stored in the workflow directory and can be accessed through the WF_USER_ROLES view.

Responsibilities

Responsibilities represent a special type of role that identifies the menu tree defined for a specific application. Responsibilities are what end users see on the left side in the navigator after login. The menu items accessible within each menu tree / responsibility are determined by the permissions the user has been granted (through roles assigned to the user).

Responsibilities are stored in the FND_RESPONSIBILITIES table but denormalized as roles into the workflow directory where they are identified by the NAME primary key column, and accessible through the WF_ROLES view. Responsibility assignment is stored in the workflow directory and can be accessed through the WF_USER_ROLES view.

4.4 Step 1: Develop Registration UI’s

Coding Guidelines

This section discusses the details of how to code registration pages. The coding standards are identical for all registration pages, irrespective of the type of the registration process.

Note: Currently, Oracle User Management does not support registration pages based on Forms technology stack.

Some generic steps to be following irrespective of the technology used to implement the registration pages

1) Define functions / permissions representing the pages to be built (see the Oracle Applications System Administrators Guide – Security for information on how to define functions / permissions).

2) Create a permission set and add all the permissions representing your registration pages

to this set.

3) Grant the permission set to the “GUEST” user account. NOTE: This is only required for permission sets that contain permissions/functions representing registration UI’s for self service account requests.

Page 12 of 31

4) Also grant the permission set to the “GLOBAL” role (a role implicitly representing all users, except the GUEST account). NOTE: This is required for all permission sets containing permissions/functions representing registration UI’s, regardless of the type of registration process.

Registration Pages using OA Framework

The traditional approach to code pages with the OA Framework and BC4J is to design Entity Objects (EOs) to represent the data model and business rules, and define View Objects (VOs) on top of the EOs for presentation purposes.

With Oracle User Management you must write your pages according to the standards provided for OA Framework development, with some Oracle User Management specific tweaks.

EOs are normally designed to write data into database tables upon commit (or call API’s with the same function). Since registration data should not be written into the destination schema until each request is approved (to avoid garbage data in your production tables), you will instead have your EOs write the information collected in the registration UI into a RegistrationBean object, a helper class provided by Oracle User Management.

The following represent the steps required to build a registration page:

5) All registration pages must be defined as self-secured as they must be accessible from any session. Please ensure you follow the OA Framework guidelines for writing bookmarkable pages.

6) Define a method named initiateRegProcess in the Application Module (AM) for your registration UI as follows:

import oracle.apps.fnd.umx.registration.RegistrationAdmin; // Method to be coded in AM, contains the logic to instantiate the RegistrationBean. // @param umxRegParams any registration data and context passed from wherever // the request originated. public void initiateRegProcess(String umxRegParams) { // instantiate the RegistrationBean and pass the current transaction. The // RegistrationBean can from now on be accessed through the transaction cache. // A commit listener is also registered by this method, this will transform the // RegistrationBean into a workflow business event object at the end of the /// registration flow and invoke the Oracle User Management registration engine. // // The method instantiateRegBean() has been designed to do nothing if // RegistrationBean has already been instantiated, so you don’t have to check for // any condition before calling this method RegistrationAdmin.instantiateRegBean(umxRegParams, getOADBTransaction()); // perform any other initialization here ……… ……… }

7) In the processRequest method of the controller associated with the first page of your

registration UI, call the API defined above, and pass the UMXRegParams parameter available in the pageContext object

Page 13 of 31

import oracle.apps.fnd.umx.registration.RegistrationAdmin; // processRequest() method of the first page in your registration UI flow. public void processRequest(OAPageContext pageContext, OAWebBean webBean) { super.processRequest(pageContext, webBean); // Read value of the registration parameter String umxRegParams = pageContext.getParameter(“UMXRegParams”); // Call method in AM to instantiate RegistrationBean // Combine any other instantiation logic that // you have in this method Serializable[] parameters = { umxRegParams }; OAApplicationModule am = pageContext.getApplicationModule(webBean); am.invokeMethod("initiateRegProcess()",parameters); // Any other logic goes here ……… ……… }

8) The destination of any “Submit” and “Cancel” buttons in your registration UI should be

based on information available in RegistrationBean. When user clicks on the “Submit” button, user should be forwarded to the URL retrieved from the method RegistrationBean.getSuccessURL(). Similarly, when user clicks on the cancel button, user should be forwarded to the URL retrieved from the method RegistrationBean.getCancelURL(); NOTE: If you are building registration UI’s you must ensure you forward to the originating or target page after the request has been submitted (or cancelled). The originating / target pages can be the Oracle User Management Access Requests page, the User Administration UI, the login page, or your own pages.

9) All your Entity Objects and View Objects should be coded as per the OA Framework standards, but with a subtle difference; the information captured in the registration UI should be set into the RegistrationBean from the insertRow method of your EOs. The RegistrationBean object instance can be retrieved from the transaction cache by calling RegistrationAdmin.getRegistrationBean. NOTE: Your EOs must extend from the class OAPlsqlEntityImpl NOTE 2: The values that set in the RegistrationBean must be defined as strings and in canonical format. The class oracle.apps.fnd.framework.OANLSServices has necessary methods to convert your native datatypes to strings in canonical format.

import oracle.apps.fnd.umx.registration.RegistrationAdmin; import oracle.apps.fnd.umx.registration.RegistrationBean; // Example of overridden insertRow() method of an Entity Object, designed to write // registration data into the RegistrationBean instead of the database. { // To set attributes in insertRow() of your EO: // 1. retrieve instance of RegistrationBean RegistrationBean regBean = RegistrationAdmin.getRegistrationBean(getOADBTransaction());

// 2. Call methods on regBean to set the information stored in the EO

Page 14 of 31

regBean.setFirstName(getPersonFirstName()); regBean.setMiddleName(getPersonMiddleName()); }

10) You are not allowed to commit any data before the end of a registration flow, this would

invoke the commit listener prematurely. All the data in the entire flow must be committed as a single unit.

11) In the processFormRequest method of the final page in the registration flow, add a call to getOADBTransaction().commit(). When this code is invoked, the BC4J framework will invoke the previously registered commit listener. See the Registration Architecture section for more information on what goes on in this method. If this process generates an exception, all the data (including Workflow) will be rolled back. If you are catching an exception while committing the data, you need to issue an explicit rollback. After calling commit, if everything went well and no exceptions were raised, get the confirmation number and status of the request from the registration bean. Forward to a confirmation page and display the status accordingly.

12) You can find out if identity verification is required or not by calling the getIdentityVerificationReqd() method in the RegistrationBean. You may want to indicate to the user that the request will not be processed until an email response has been received.

13) Ensure you define subscriptions to appropriate business events raised by the Oracle User

Management registration engine. Your subscriptions will be invoked after the request has been approved. Ensure that the subscription logic reads the registration data stored in the event object and writes it to the destination schemas / tables. See Subscribing to Business Events & Handling Registration Data for detailed information on the business events you must subscribe to and how to define your subscription logic.

Generating link to launch registration flow For self-service account request registration flows, product teams should generate the link to their page flow using the generateRegistrationURL() method, defined in the oracle.apps.fnd.umx.util.URLFramework class. Details can be found in the integration Repository.

Coding “OA Framework Independent” Self Service Account Request Registration Pages

Oracle User Management is designed primarily for the OA Framework; the following are some general guidelines if you are coding your self-service account request registration pages using some other technology (for example: jsp). These are general guidelines only and not explicitly supported:

1. Your pages must be registered as functions.

2. You need to retrieve the UMXRegParams parameter from the HTTP request object on the first page of the flow.

3. Call the RegistrationAdmin.createRegistrationBean method with UMXRegParams as an input parameter to instantiate an instance of RegistrationBean. You are responsibly for preserving the state of this instance throughout the page flow. If you don’t want to keep this instance around or if your application is completely stateless and you cannot preserve the state, it is recommended that you create this instance just before you commit your registration data. In this case, you need to maintain the value of UMXRegParams until you create an instance of RegistrationBean.

Page 15 of 31

4. Just before you commit your data in the last page of the registration flow, call the RegistrationAdmin.processRegistrationRequest method. If you get an exception during this call, you must rollback all of your changes.

5. After commit, inspect the instance of RegistrationBean to retrieve post-commit information such as a confirmation number. You will need to design your confirmation page based on this information. You also need to determine whether identity verification is enabled (through the RegistrationBean) and indicate this to the requester.

6. Ensure you define subscriptions to appropriate business events raised by the Oracle User Management registration engine. Your subscriptions will be invoked after the request has been approved. Ensure that the subscription logic reads the registration data stored in the event object and writes it to the destination schemas / tables. See Subscribing to Business Events & Handling Registration Data for detailed information on the business events you must subscribe to and how to define your subscription logic.

4.5 Step 2: Subscribing to Business Events & Handling Registration Data

Overview & General Guidelines

The Oracle User Management registration engine raises business events to signify starting or completion of several significant activities. An event object holding all the registration data is defined as the payload for the business events and available to the subscribers (see the Registration Architecture section for more information). The following is a list of business events that are raised by Oracle User Management: Oracle User Management Workflow Business Events

Event Description oracle.apps.fnd.umx.rolerequested Event raised when a role is requested. oracle.apps.fnd.umx.accountrequested Event raised when an account is requested. oracle.apps.fnd.umx.requestapproved Event raised when an account or role request is approved. oracle.apps.fnd.umx.requestrejected Event raised when an account or role request is rejected. <business logic event, if defined> with the context “ROLE APPROVED”

Event raised in additional access flows NOTE: If your registration process is defined for additional access, the oracle.apps.fnd.umx.createpersonparty event (defined below) is not raised. You must therefore write any registration data to the target schema by providing subscribing logic for this event..

<business logic event, if defined> with the context “BEFORE ACCOUNT ACTIVATION”

Event raised in account provisioning flows to get a person party created in TCA. NOTE: The owner of the registration process must register a subscription to this event and create a person party in TCA. Any other registration data that can be written to the destination schemas without requiring an active user account should also be handled by the subscription logic (such as organization relationships or any other information related to the person party). NOTE: Once the person party has been created, the subscription must update the event object with the person party id by setting the PERSON_PARTY_ID name-value pair (see code sample below). Once the person party is available in the event object, the Oracle User Management registration engine will activate the user account and link it with the person party.

<business logic event, if defined> with the context “AFTER ACCOUNT ACTIVATION”

Event raised in account provisioning after user account has been created. NOTE: The owner of any account provisioning registration processes must register a subscription to this event if any of the registration data require foreign keys to the user account (such

Page 16 of 31

as profile options), and ensure that the information is written into the target schemas.

The Oracle User Management registration engine automatically populates the event parameters listed in the following table when business events are raised. Any additional information captured in the registration UI, approval notifications, or programmatically through business logic are also defined as event parameters.

Oracle User Management Business Event Parameters Name Description REG_SERVICE_CODE Represents the primary key of the registration process REG_SERVICE_TYPE The type of registration process REQUESTED_BY_USER_ID Identifies the user submitting the request REQUESTED_FOR_USER_ID Identifies the user for whom the request is submitted REQUESTED_USERNAME The requested user name WF_ROLE_NAME* Represents the primary key value of the requested role (or the default

role defined for any account provisioning registration processes) AME_TRANSACTION_TYPE_ID Represents part of the primary key for the transaction type in

Oracle Approval Management AME_APPLICATION_ID Represents part of the primary key for the transaction type in Oracle

Approval Management

*WF_ROLE_NAME is not required for Self Service Account Creation or Account Creation for Administrators registration processes. In such cases, a null value is passed. Any additional information captured in the registration UI, from approvers, in approval notifications, or set by business logic are also available as parameters in the event object whenever any of the business events defined above are raised by Oracle User Management.

So to repeat, anyone building their own registration processes must ensure that they define the business logic events and provide subscriptions to the appropriate business event(s) and write registration data held in the event object to the destination schema for each approved request. Specifically, this entails subscribing to the custom business logic events, defined/owned by product teams owning the registration process. Also refer to the Registration Architecture section for detailed information on the flow of events.

Synchronous vs. Asynchronous Subscriptions

All subscriptions to the business events listed above should be defined as asynchronous (phase greater than 100) unless there is a requirement that the subscription must finish before the next activity in the main registration workflow.

An example of where synchronous processing is required is subscriptions for the business logic event. These subscriptions must be synchronous since the Oracle User Management registration engine requires a person party to be created before processing can continue. Synchronous subscriptions to business events have performance impact and may slow down the overall processing. Any exceptions that may occur in the asynchronous events will not be propagated back to the registration engine and will be ignored, although the system administrator is notified of any such failures and can take action. For general information on how to register a subscription and handle business events, please refer to the Oracle Workflow Administrator's Guide.

Event Subscriptions: Sample Code

The following is an example of a subscription for creating a person party:

procedure custom_logic (p_subscription_guid in raw, p_event in out NOCOPY WF_EVENT_T) return varchar2 is

l_first_name varchar2(30); l_last_name varchar2(30); l_event_context varchar2(30); l_person_party_id number; begin // Only do something if the context is appropriate. L_event_context := p_event.getvalueforparameter ('UMX_CUSTOM_EVENT_CONTEXT');

Page 17 of 31

if l_reg_process = ‘BEFORE ACCOUNT ACTIVATION’ then // get first and last name from the event object, the most common // parameter names are predefined in the RegistrationBean, but // custom parameters are also supported l_first_name := p_event.getvalueforparameter ('FIRST_NAME'); l_last_name := p_event.getvalueforparameter ('LAST_NAME'); // create person party in TCA here l_person_party_id := someAPIThatCreatesPersonParty(l_first_name,l_last_name); //Call UMX_PUB.updateWfAttribute() to set the person_party_id back into the //registration engine. This is required so that the user account can be //activated and linked to the person party. The attribute name has to be // ‘PERSON_PARTY_ID’ UMX_PUB.updateWfAttribute (p_event => p_event, name => ‘PERSON_PARTY_ID’ value => l_person_party_id);

end if; end custom_logic;

4.6 Step 3: Define Notification Workflows

Oracle User Management ships two sample notification workflows, one to be used for additional access requests, and another for account provisioning requests. Customization of the predefined notification workflows are not supported, instead:

1. Copy one of the sample notification workflows provided by Oracle User Management:

Name Item Type Description Additional Access Request Notification Workflow

UMXNTWF1 Generic notification workflow for requests for additional access.

Account Provisioning Notification Workflow

UMXNTWF2 Generic notification workflow for account provisioning flows.

Example of Notification

Page 18 of 31

Workflow:

When defining your notification workflows, there are a couple of questions you should ask yourself:

• What information entered by the requester should be included in identity verification and approval emails?

• What information, if any, should the approver be able to change or provide when approving the request?

2. Add any item attributes you want to display in the email notifications. If the values for these attributes were captured in the registration UI, ensure that the name is exactly the same as the name-value pairs originally set in the RegistrationBean (and later in the event object).

3. Change the notifications as per your requirements. A few notes:

a. Only make the absolutely minimum changes required in your copy of the notification workflow. Everything is there for a reason; so don’t mess with things unless you have a very good reason to! The only activities you should change are the notifications within the red rectangle in the diagram above (notify approver, verify the requesters identity, request approved notification, request rejected notifications). You can add activities before and after each of these activities although you must ensure that the general flow is kept intact.

b. Since each organization and deployment has their own unique requirements, each notification workflow must be designed to support identity verification, approval, confirmation, and rejection email notifications.

Page 19 of 31

c. All the data that was collected during the registration flow will be passed to the notification workflow as part of the event object; this includes any server / deployment specific registration parameters part of the registration URL wherever the request was initiated from. Any item attributes that have the same name as a parameter stored in the event object will automatically be populated with the corresponding value. Please refer to the Subscribing to Business Events & Handling Registration Data section for information regarding what parameters are populated automatically in the event object by Oracle User Management.

d. If your notifications allow the recipient to provide new (or alter existing) information, you need to ensure that the changes are reflected in the event object (so that the information is available in later steps in the registration flow). The following is some pseudo code for the custom activity Modify Event Object in the diagram below, this activity updates the event object with security clearance information provided by the approver.

// NOTE: This is pseudo code only declare l_registration_data wf_event_t; l_parameter_list wf_parameter_list_t; l_param_name varchar2(30); //must match wf_parameter_t.name%type l_param_value varchar2(2000); //must match wf_parameter_t.value%type begin // The wf attribute holding the changed/new value provided by the approver l_param_name := ‘SECURITY_CLEARANCE’;

Page 20 of 31

// get the value of the wf attribute, see workflow API doc for up to date info // on how to retrieve attribute values l_param_value := wf_engine.getItemAttrText(item_type, item_key, actid, l_param_name); // Get a handle to the event object l_registration_data := wf_engine.getitemattrevent(item_type,item_key,'REGISTRATION_DATA'); // Get a handle to the parameter list, part of the event object l_parameter_list := l_registration_data.getparameterlist(); // Now set the changed/new name-value pair into the event object, // so it is available to any subsequent logic wf_event.addParametertoList(l_param_name,l_param_value,l_parameter_list); end;

e. The notification workflows already include all code required to pass both status

and any changed or new parameter values in the event object back to the User Management registration engine.

4. Register a new business event (see the Oracle Workflow Business Event documentation for details) that will be used to invoke your notification workflow. NOTE: The OWNER_NAME field of the business event must begin with “UMX:” followed by the name of your application, for example: “UMX: Oracle Learning Administration”. It is important to follow this naming convention as the registration process setup UI only displays business events following this convention.

5. Update your registration process definition (through the User Management Registration Process setup screen) and define the business event created in the previous step as the “Notification Event”.

6. Register your notification workflow as an asynchronous subscription (phase > 99) to the business event defined in the previous step

4.7 Step 4: Define Approval Routing Rules

Overview

Each organization will have different requirements in regard to what registration requests require approval, and who should approve each request. Oracle User Management integrates with Oracle Approval Management which provides a rule-based engine that determines the flow of the approval process.

This section provides guidelines for how conditions defined in Oracle Approval Management can be based on information captured in the registration flow (information stored in the event object for the request). Please refer to Oracle Approval Management documentation for general guidelines on how to setup conditions and approval chains.

Routing Approvals based on Registration Data

In the following example, a set of approval routing rules will be defined (a.k.a. Approval Transaction Type) in which a request will be routed to a country specific approver

Page 21 of 31

(US_APPROVER or UK_APPROVER) based on the ORIG_COUNTRY parameter defined as part of the registration URL on the login page.

a. Log into Oracle Approvals Management

b. Create a new transaction type

c. Create a new non-mandatory attribute “ORIG_COUNTRY” with no static usage for this transaction type, and enter the following SQL into the usage area: select umx_pub.get_attribute_value(:transactionId, 'ORIG_COUNTRY'); NOTE: The :transactionId parameter is set by the Oracle User Management registration engine at runtime, and corresponds to the ITEM_KEY of the notification workflow. NOTE: The second parameter, in this case ORIG_COUNTRY, can be any parameter name set in the RegistrationBean / event object.

d. Create the following two conditions using the attribute “ORIG_COUNTRY” created in the previous steps. condition_for_US_requests ORIG_COUNTRY = US condition_for_UK_requests ORIG_COUNTRY = UK

e. Create the following two rules: rule_for_US_requests if (condition_for_US_requests) then approver = 'US_APPROVER' rule_for_UK_requests if (condition_for_UK_requests) then approver` = 'UK_APPROVER'

f. Oracle Approval Management transaction types can be associated with any registration process, once they are defined in the system. Please ensure that the Transaction Types are specifically designed to work with Oracle User Management before selecting them. See the Setting Up Registration Processes section of the Oracle Applications System Administrators Guide – Security for more information.

4.8 Step 5: Extracting Seed Data

This section describes the details on downloading and uploading roles and registration processes. Organizations can use these loaders to transfer data between two instance and Oracle product teams can use these loaders to ship seed data.

NOTE:Please contact the Oracle User Management Development team for information on how to extract Roles, Role Inheritance Hierarchies, Role Categories, Grants, Permission Sets, Permissions, and Registration Processes. This type of seed data must be reviewed and approved before shipped to customers.

Page 22 of 31

5. User Name Policy – Administration and Customization

User Name policy

Overview

Oracle User Management supports customizable user name policy. A user name policy is used to determine the format for the username e.g. email or firstname.lastname or based on some business logic specific to the installation.

The user name policy infrastructure enables to display the policy related information in UI, generate a suggested user name and validate the user name format

There are three basic components to the policy

• Suggested User Name Generation

• User Name Policy Descriptions

• User Name Validation

Suggested User Name Generation

Suggested User Name is an auto generated user name – mostly for the purpose of display in registration UI’s, with which the user could register. It is designed to offer a suggestion for the user name and typically, the registration UI should allow the suggestion to be changed, if necessary as per business/validation requirements. The Suggested User Name makes it easier for the user and administrator when registering or creating a user account for an existing person in the system.

Before the user registration page with the user name field is rendered, the registration UI invokes User Management public APIs to get the suggested user name.

The API to get suggested user name raises a Workflow Business Event named oracle.apps.fnd.umx.username.generate with the person party ID from the HZ_PARTIES table. The current implementation requires that person party id is present.

Only one valid synchronous subscription listens to this event. The subscription will generate and return the suggested user name. In case the user name cannot be generated, the subscription returns a null value. The provisioning UI that invokes this API should account for the null value and handle it appropriately.

Usage Guidelines for developers

Work In Progress

Disclaimer

The suggested user name generation component of the user name policy has been implemented by Oracle User Management provisioning flows – “Employee Registration” and “Create Account for Existing Person”. Other products in Oracle Applications Suite may not have implemented this component of the user name policy. Customers can create their custom policy, but the behavior in the other flows is not known at this time.

Page 23 of 31

User Name Policy Descriptions

To help the display of appropriate field names in various registration flows, the user name policy descriptions allow for three types of descriptions for the User Name Policy.

• Policy Description describes the defined policy. For example: “User Names must be based on Email Address”. This statement can be displayed as a quick tip section in the user account registration page.

• Prompt is the word being displayed next to the user name text input field as illustrated

below

• Hint gives an example of what the format of the user name should be. It could be displayed as a tip text of the user name text input field in the UI. The Hint displayed in the example above is “example: michael@email.com”.

These descriptions are stored in a FND lookup. Each policy has a lookup associated with it. These lookups have to be defined with the prefix of “UMX_USERNAME_POLICY:” and should consist of three lookup codes DESCRIPTION, PROMPT and HINT. The “Meaning” field within the lookup contains the actual value for each of the policy descriptions.

For example, taking the Email Address Format Policy:

FND Lookup Type

Lookup Type: UMX_USERNAME_POLICY:EMAIL Meaning: User Name Policy: Email Address Application: Application Object Library Description: User Name Policy with email address format defined as the policy FND Lookup Code

Code Meaning Description

DESCRIPTION User Names must be based on Email Address

Description describes the User Name Policy.

PROMPT User Name Prompt of the user name text input field.

HINT example: michael@email.com Text that provides the example of the User Name Policy.

The profile option UMX: User Name Policy (UMX_USERNAME_POLICY), defined at site level stores the name of the lookup type of the descriptions for the current policy.

Usage Guidelines for developers

Work In Progress

Disclaimer

Page 24 of 31

The user name policy descriptions component of the user name policy has been implemented by Oracle User Management provisioning flows. Other products in Oracle Applications Suite may not have implemented this component of the user name policy. Customers can create their custom version, but the behavior in the other flows is not known at this time.

User Name Validation

Based on business requirements, all new users created in the system might have to conform to a specific format. The user name validation infrastructure is provided to allow customization of the user name format validation.

The API to create a new user or test user name ( TestUserName() or createUser() in FND_USER_PKG) raise an event oracle.apps.fnd.user.name.validate. The user name format is validated as part of the subscription for this event.

Oracle User Management ships a sample synchronous subscription that will contain email address as the policy. The function for the sample validation subscription is FND_USER_VALIDATION.Custom_Validation.

Usage Guidelines for developers

Work In Progress

Disclaimer

If enabled, user name validation is enforced through the central user provisioning APIs for all of Oracle Applications Suite.

The user name validation component of the user name policy has been certified with Oracle User Management provisioning flows and by some of the CRM product teams like iRecruitment and Service Contracts at this time. Additional patching may be required from these products. Custom validation polices created by customers can throw exceptions which will be handled gracefully in these UI provisioning flows.

Other products in Oracle Applications Suite may not have implemented this component of the user name policy in their provisioning UI flows. Validation exception handling behavior in such flows is not known at this time.

Administration - Configuring the User Name Policy

The Oracle User Management registration infrastructure supports a configurable user name policy. This policy is used to generate a suggested user name in the sample user creation flows shipped with the application, as well as for validating the chosen user name format.

Note: Oracle User Management is shipped with a default policy that identifies users by their email address.

Seeded User Name Policies

The following table lists the seeded user name policies that are shipped with Oracle User Management.

Page 25 of 31

Code Description UMX_USERNAME_POLICY:EMAIL_ADDRESS

User name policy with email address format defined as the policy.

UMX_USERNAME_POLICY:NONE User name policy with no restriction on username format

Administrators can configure either of these seeded policies. In addition to these, custom policies can also be implemented if desired. The process to create new policy is described in the next section.

Configuration of user name policy is a three-stage process.

Stage 1 - Suggested User Name Generation Subscription Setup

1. Log on as a user that is assigned the Workflow Administrator Web Applications responsibility (typically sysadmin).

2. Go to Workflow Administrator Web Applications > Business Events

3. From the Business Events page, search for the Business Event with the name oracle.apps.fnd.umx.username.generate

4. Click on the Subscription icon to go to the Subscriptions page.

5. For the subscription corresponding to the policy to be enabled, change the status to “Enabled”.

Note:

• Please ensure that only one subscription is enabled for this event. For all the other subscriptions, change the status to disabled.

• The subscription should be synchronous (phase < 100)

Stage 2 - Profile Option Setup

1. Log on as a user that is assigned the Functional Administrator responsibility (typically sysadmin).

2. Go to Functional Administrator > Core Services > Profiles

3. Search with the Profile Name of UMX: User Name Policy in the Maintain Profile Options page.

4. Click on the Update icon to go to the Update Profile Option page.

5. Choose a value corresponding to the policy to be enabled and click on the Apply button.

Stage 3 - Validation Event Subscription Setup

1. Log on as a user that is assigned the Workflow Administrator Web Applications responsibility (typically sysadmin).

Page 26 of 31

2. Go to Workflow Administrator Web Applications > Business Events

3. From the Business Events page, search for the Business Event with the name oracle.apps.fnd.user.name.validate

4. Click on the Subscription icon to go to the Subscriptions page.

5. For the subscription corresponding to the policy to be enabled, change the status to “Enabled”.

Note:

• Multiple subscriptions “can” be enabled for this subscription, if necessary.

• The subscription should be synchronous (phase < 100)

Additional Requirements

• For all the three of the stages above, the values set must generally correspond to the same user name policy.

• The Listener and JVMs must be restarted after the user name policy is changed.

Customization – Creating a new user name policy

To create a user name policy, any or all of the three components can be implemented, based on business requirements.

Suggested User Name Generation

The public API for generating suggested username - UMX_PUB.get_suggested_username raises the event oracle.apps.fnd.umx.username.generate. A synchronous subscription of this event returns the suggested user name. The event is raised with UMX_PERSON_PARTY_ID, the person party ID in the event object. The subscription can leverage the ID to generate the suggested user name. The subscription should return the generated user name in the parameter UMX_GENERATED_USERNAME of the event object. If the suggested user name cannot be generated, null value should be returned.

Oracle User Management ships a sample subscription for this event. This sample subscription generates a suggested user name based on the email address of the person.

To create a customized suggested username policy:

1. Implement a policy subscription function as a PL/SQL function. The sample given below can be used as a starting point.

Note: Since UI could rely on the output of the subscription for render, the subscription function needs to be synchronous and have good performance.

Sample code for the subscription function:

function policy_subscription (p_subscription_guid in raw, p_event in out nocopy WF_EVENT_T) return varchar2 is

Page 27 of 31

l_username fnd_user.user_name%type; begin -- Call the appropriate procedure here to generate username -- based on the person party id input provided. UMX_REGISTER_USER_PVT.Get_Party_Email_Address ( p_person_party_id => p_event.getValueForParameter ('UMX_PERSON_PARTY_ID'), x_email_address => l_username); -- Returning the generated username, if any. If no username -- is being returned, then the value returned should be null p_event.addParametertoList('UMX_GENERATED_USERNAME', l_username); return 'SUCCESS'; -- unhandled exceptions. Return error only if real exception -- if user name cannot be generated, return SUCCESS status will -- null value for the generated user name exception when others then WF_CORE.CONTEXT('<package name>', '<function name>', p_event.getEventName( ), p_subscription_guid); WF_EVENT.setErrorInfo(p_event, 'ERROR'); return 'ERROR'; end policy_subscription;

2. Register the subscription function created in step above as the synchronous subscription for the event oracle.apps.fnd.umx.username.generate. To register the subscription

o Log on as a user that is assigned the Workflow Administrator Web Applications responsibility (typically sysadmin).

o Go to Workflow Administrator Web Applications > Business Events

o From the Business Events page, search for the Business Event with the name oracle.apps.fnd.umx.username.generate

o Click on the Subscription icon to go to the Subscriptions page.

o Click on “Create Subscriptions”

o Relevant values to be set

Phase – Less than 100

Status – Enabled (If you want policy to be active)

Rule Data – Message

Action Type – Custom

On Error – Stop and Rollback

o Click “Next” and define your PL/SQL Rule Function created in step 1 above here

Page 28 of 31

o Click “Apply”

3. Ensure that only one subscription is active for this event.

User name Policy Descriptions

The user name policy descriptions lookup provides the prompt, hint and description for the user name field in registration UI’s. If custom policy has been created, it might be necessary to implement a new lookup to get the registration UI’s display correct prompt and hints.

To create custom policy descriptions

• Create a new FND lookup type starting with a prefix of UMX_USERNAME_POLICY:

• Create three lookup codes in this lookup with the codes – PROMPT, DESCRIPTION and HINT and set the lookup meaning to appropriate values

• Set the profile option UMX: User Name Policy to point to this new lookup created in step above.

Validate User Name Format

Public APIs to create/update a user, raise a business event - oracle.apps.fnd.user.name.validate. The user name format is validated by the subscription associated with the event. The subscription obtains the user name from the event key and validates the user name format.

The subscription for this event needs to be a synchronous.

Error handling, in case of user name is not in a valid format, is done as:

1) Invoke wf_event.setErrorInfo to set the status to ERROR.

2) Set a message into the FND message stack that describes the reason the validation failed.

3) Invoke app_exception.raise_exception to raise an exception.

Unlike suggested user name generation, there could be more than one active subscriptions listening to the event to validate the user name format as long as the subscriptions do not have conflict in terms of the policy.

Here is a sample of subscription function that validates email address format:

function policy_subscription (p_subscription_guid in raw, p_event in out nocopy WF_EVENT_T) return varchar2 is l_username fnd_user.user_name%type; begin l_user_name := p_event.getEventKey(); l_dot_pos := instr( l_user_name, '.'); l_at_pos := instr( l_user_name, '@'); l_str_length := length(l_user_name); if (

Page 29 of 31

(l_dot_pos = 0) or (l_at_pos = 0) or (l_dot_pos = l_at_pos +1 ) or (l_at_pos = 1) or (l_at_pos = l_str_length) or (l_dot_pos = l_str_length) )then -- setting error message on the stack so that it can be displayed -- by the calling code WF_EVENT.setErrorInfo(p_event,'ERROR'); FND_MESSAGE.SET_NAME('FND','FND_INVLD_EMAIL_FRMT'); -- we are raising an app exception since Fnd_user_pkg.validate -- expects an exception. app_exception.RAISE_EXCEPTION; end if; return 'SUCCESS'; end policy_subscription;

If needed, a custom policy subscription can be created for validating the user name format. To create a subscription for the event oracle.apps.fnd.user.name.validate, follow the steps outlined in the Suggested User name section above.

Page 30 of 31

6. Appendix A: Java Doc Java doc for Oracle User Management is available at the online integration repository. Here are the steps to access the repository.

• Go to http://irep.oracle.com

• Click on product family “Applications Technology”

• Click on product “User Management”

• Click on the various entities to view the available methods/classes associated with them

Page 31 of 31