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 1.0 Created R12 version.

Development
1/31/07 Oracle User Management 1.0 Published document.
Documentation

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

Event
Object Raise
Business
Event
Register Enter Info Submit
Request Event
Object

Email
To Approver(s)
Event Event Event
Object Object Object

Confirmed!

Verify Identity Reserve Invoke

via Email User Name Registration Engine
Event Approved!
Object

Event Event Event Event

Object Object Object Object

Create Activate Write Assign Confirmation

Person Party User Account Registration Data Roles Email

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 Event raised in additional access flows
the context “ROLE APPROVED”
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 Event raised in account provisioning flows to get a person party
the context “BEFORE ACCOUNT created in TCA.
ACTIVATION”
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 Event raised in account provisioning after user account has been
the context “AFTER ACCOUNT created.
ACTIVATION”
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 UMXNTWF1 Generic notification workflow for requests for
Notification Workflow additional access.
Account Provisioning UMXNTWF2 Generic notification workflow for account
Notification Workflow 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 Description describes the

Email Address 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_ User name policy with email
ADDRESS 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