Step 4: Setting Up an Oracle Workflow Directory Service

Oracle Workflow requires a directory service to provide information about the individuals and roles in your organization who may utilize Oracle Workflow functionality and receive workflow notifications. Oracle Workflow references this user and role information through the following views.

See: Workflow Directory Service Views.

Oracle Workflow provides a predefined directory service for you that is implemented by default during installation, with directory service views for users and roles from the unified Oracle E-Business Suite environment. See: Setting Up a Directory Service for Oracle Workflow.

You can also create your own directory service by defining custom views with the required columns. However, note that only the predefined directory service provided by Oracle Workflow is supported by Oracle. See: Oracle Workflow Support Policy.

Oracle Workflow provides local directory repository tables called WF_LOCAL_ROLES and WF_LOCAL_USER_ROLES. These tables should always be included in any implementation of the WF_USERS, WF_ROLES, and WF_USER_ROLES views.

Oracle Workflow also provides tables to support extended directory service features.

The Workflow local tables store denormalized user and role information originating from various other Oracle E-Business Suite modules, so that the directory service views can access this information with good performance. You can also use these tables to store ad hoc users and roles by calling the appropriate Workflow directory service PL/SQL APIs.

You should periodically purge ad hoc users and roles from the Workflow local tables after they have expired in order to improve performance. See: Directory.

For more information, see: Workflow Directory Service APIs, Ad Hoc Users and Roles, and Oracle Workflow Security.

arrow icon   Setting Up a Directory Service for Oracle Workflow:

Oracle Workflow uses a directory service model in which denormalized information is maintained in the Workflow local tables for performance gain. The Workflow local tables store user and role information originating from various other Oracle E-Business Suite modules, as well as ad hoc users and roles, so that the WF_USERS, WF_ROLES, WF_USER_ROLES, and WF_USER_ROLE_ASSIGNMENTS_V views can access this information with good performance. Oracle E-Business Suite ensures synchronization is maintained between the user and role information stored in application tables by the source modules and the information stored in the Workflow local tables.

Directory Service Views

The predefined WF_USERS, WF_ROLES, WF_USER_ROLES, and WF_USER_ROLE_ASSIGNMENTS_V directory service views for Oracle Workflow are based solely on the Workflow local tables where the denormalized information is stored. These view definitions are automatically created for you during installation. See: Workflow Directory Service Views.

Note: You can customize your directory service by creating your own custom view definitions, provided that you define the required columns and map to the Workflow local tables. However, note that only the predefined directory service views provided by Oracle Workflow are supported by Oracle. See: Oracle Workflow Support Policy.

The only roles in WF_LOCAL_ROLES that are marked as individual users with the user flag set to Y are roles that represent Oracle E-Business Suite users, originating from the FND_USER table, roles that represent Oracle Trading Community Architecture (TCA) person parties, roles that represent TCA contacts (relationship parties), or roles that represent ad hoc users. Records originating from other application tables are treated solely as roles, with the user flag set to N. The WF_LOCAL_USER_ROLES table is used to associate Oracle E-Business Suite users, TCA person parties, and TCA contacts with roles defined by other applications.

Note: An Oracle E-Business Suite user may be associated with an Oracle Human Resources person. In this case, some person information is combined into the user's record in WF_LOCAL_ROLES. In such a combined record, the originating system is changed from FND_USR to PER, and the display name is taken from Oracle Human Resources, while the internal name is the Oracle E-Business Suite user name from FND_USER, and the user flag is still set to Y.

Each Oracle Human Resources person is also represented in WF_LOCAL_ROLES as a role with the originating system PER_ROLE and the user flag set to N. This record remains unaffected whether the person is linked to an Oracle E-Business Suite user or not.

The following table summarizes the different ways in which Oracle E-Business Suite users and Oracle Human Resources people are stored in WF_LOCAL_ROLES.

Oracle E-Business Suite Users and Oracle Human Resources People in WF_LOCAL_ROLES

Type of Role Orig_System User_Flag
Oracle E-Business Suite user, not linked to an Oracle Human Resources person FND_USR Y
Oracle E-Business Suite user linked to an Oracle Human Resources person PER Y
Oracle Human Resources person PER_ROLE N

To link an Oracle E-Business Suite user to an Oracle Human Resources person, navigate to the Users window in Oracle E-Business Suite and select the appropriate person name in the Person field for that user. See: Users Window.

You should only link an Oracle Human Resources person to one Oracle E-Business Suite user. If a person is linked to more than one user, notifications for that person may become inaccessible, and workflow processes may be halted while waiting for those notifications to be completed. Additionally, assigning a person to multiple users may cause errors in other Oracle E-Business Suite modules as well. For this reason, you must not link an Oracle Human Resources person to more than one Oracle E-Business Suite user.

The WF_LOCAL_ROLES and WF_LOCAL_USER_ROLES tables are partitioned by the originating system within Oracle E-Business Suite that was the source of the denormalized information. This partitioning provides faster data access and also allows each originating system to be synchronized with the Workflow local tables individually. Each table also includes a separate partition that contains ad hoc users and roles as well as data from any system that does not have its own partition.

The partition information for each originating system is stored in the WF_DIRECTORY_PARTITIONS table. There are partitions for the following systems:

Note: Normally each partition contains only records that originate from the corresponding system. However, the FND_USR partition can contain both roles with an originating system value of FND_USR, which are unlinked Oracle E-Business Suite users, and roles with an originating system value of PER, which are Oracle E-Business Suite users that are linked to Oracle Human Resources people.

See: Ad Hoc Users and Roles.

Synchronizing Workflow User and Role Information

For each Oracle E-Business Suite module that is a source of Oracle Workflow user and role information, the information stored in the source application tables is synchronized with the denormalized information in the Workflow local tables. The Workflow local synchronization APIs are used to perform this synchronization.

Oracle Workflow automatically performs an initial synchronization of the user and role information in all the related originating systems during installation. Subsequently, each Oracle E-Business Suite module that stores user and role information in its application tables automatically synchronizes that information with the information in the Workflow local tables on an incremental basis, using the Workflow local synchronization APIs.

Role Hierarchies

Roles can be related to each other in a hierarchy so that users assigned to one role automatically inherit membership in its superior roles as well. Role hierarchies enable role-based access control in Oracle E-Business Suite.

For example, a company could define a role hierarchy with three roles: sales manager, sales representative, and employee. A user with the sales manager role automatically inherits the sales representative role, and a user with the sales representative role automatically inherits the employee role. If user A is assigned directly to the sales representative role, then user A will also have an inherited assignment to the employee role. If user B is assigned directly to the sales manager role, user B will also have inherited assignments to both the sales representative role and the employee role.

The role to which a user is directly assigned is the assigning role for that assignment and for all other assignments that the user inherits through that role's hierarchy. For instance, in the previous example, for user A the sales representative role is the assigning role for both the sales representative assignment and the employee assignment. For user B, the sales manager role is the assigning role for the sales manager assignment, the sales representative role assignment, and the employee role assignment.

Oracle Workflow stores hierarchical relationships between roles in the WF_ROLE_HIERARCHIES table. Oracle Workflow also stores denormalized information about direct and inherited assignments of users to roles in the WF_USER_ROLE_ASSIGNMENTS table for performance gain. If a user is associated with a certain role through more than one direct or inherited assignment, the WF_USER_ROLE_ASSIGNMENTS table tracks which assignments are currently valid and expires the user/role association only when all assignments have ended.

The inheritance of roles is based on the role relationships stored in the the WF_ROLE_HIERARCHIES table. As long as a role relationship exists in this table, a user assigned to a role will inherit both expired and unexpired roles in that role's hierarchy.

The start and end dates between which an assignment is valid depend on the effective dates of the following:

The user, the assigned role, and the assigning role must all be active, that is, unexpired, in order for the assignment to be valid. The assignment does not become valid until all three are active, and if any of the three expires, the assignment is no longer valid. Additionally, the assignment is only valid as of the date it was created.

Validating Directory Service Information

You can run a diagnostic test through Oracle Diagnostics Framework to check that there are no duplicate roles in the WF_LOCAL_ROLES table. See: Oracle Workflow Diagnostic Tests.

If you encounter inconsistencies in your directory service information, Oracle Support may direct you to run the Workflow Directory Services User/Role Validation concurrent program (FNDWFDSURV) to validate and correct the information about user/role associations. You should also investigate the cause of any inconsistencies. Use Standard Request Submission to run this program, specifying the following parameters.

See: Running Reports and Programs.

arrow icon   Workflow Directory Service Views:

Oracle Workflow relies on views named WF_USERS, WF_ROLES, WF_USER_ROLES, and WF_USER_ROLE_ASSIGNMENTS_V to reference user and role information. Other views provide further access to Workflow directory service data, including WF_ALL_ROLES_VL, WF_ALL_USER_ROLES, and WF_ALL_USER_ROLE_ASSIGNMENTS. These directory service views for the unified Oracle E-Business Suite environment are automatically defined for you during installation.

Note: An expiration date can be assigned to each role in WF_LOCAL_ROLES, each user/role association in WF_LOCAL_USER_ROLES, and each user/role assignment in WF_ROLE_HIERARCHIES. After that date, an expired role is no longer included in the predefined WF_USERS and WF_ROLES view, an expired user/role association is no longer included in the predefined WF_USER_ROLES view, and an expired user/role assignment is no longer included in the WF_USER_ROLE_ASSIGNMENTS_V view.

However, note that although the expired rows no longer appear in these views, they still exist in the Workflow local tables. You should periodically purge expired ad hoc users and roles using the WF_PURGE.Directory() API in order to improve performance. See: Directory.

You can also create your own directory service by defining custom views with the required columns. However, note that only the predefined directory services provided by Oracle Workflow are supported by Oracle. See: Oracle Workflow Support Policy.

If you create your own custom view definitions:

Note: Avoid making a join to a view that contains a union, as this results in poor database performance. The Oracle Database is unable to preserve the indexes in that view when you make such a join. The workflow directory service views you create will most likely contain unions; therefore you should not join to them directly. If you need to retrieve data from any of the three directory services views, use the appropriate directory services API. See: Workflow Directory Service APIs.

WF_USERS

The WF_USERS view references information about the individuals in your organization who may utilize Oracle Workflow functionality or receive workflow notifications.

Note: In WF_LOCAL_ROLES, a role that is an individual user has the user flag set to Y.

Note: This view includes only Oracle E-Business Suite users originating from the FND_USER table, TCA person parties, TCA contacts, and ad hoc users, although an Oracle E-Business Suite user record may also include information from Oracle Human Resources if the user is linked to an Oracle Human Resources person.

The WF_USERS view must contain the following required columns:

WF_ROLES

The WF_ROLES view references information about all the roles in your organization who may utilize Oracle Workflow functionality or receive workflow notifications. This view must contain the following required columns pertaining to the roles in your repository. Those columns that are preceded by an asterisk (*) are similar to the corresponding columns described for the WF_USERS view.

Important: Each user identified by WF_USERS must also appear in the WF_ROLES view as a role. This is a requirement for Oracle Workflow.

Note: If a user is a member of a role and the user information such as language and notification preference is different from the role information, the Expand Roles option for a notification addressed to the role determines whether the user information or the role information takes precedence. If the Expand Roles option is not checked and the Notification System delivers the notification to the role, the role information will override the user information. If Expand Roles is checked, however, then each user in the role will receive a separate copy of the notification, and the user information will override the role information.

If a user has a notification preference of SUMMARY or SUMHTML, and the user is also a member of a multi-user role with a different notification preference such as MAILHTML, the Notification System will use the Expand Roles setting to determine whether to deliver the notification according to the role or user notification preference. However, even if Expand Roles is not checked and the notification preference of the role takes precedence, the notification will still appear in the user's summary message because the notification is part of the user's worklist.

WF_USER_ROLES

The WF_USER_ROLES view is an intersection of the users and roles in WF_USERS and WF_ROLES, showing which users are members of which roles.

Note: A role can contain only individual users as its members. It cannot contain another role. However, roles can be related to each other in a hierarchy so that users assigned to one role automatically inherit membership in its superior roles as well.

The WF_USER_ROLES view must contain the following required columns:

WF_USER_ROLE_ASSIGNMENTS_V

The WF_USER_ROLE_ASSIGNMENTS_V view is an intersection of the users and roles in WF_USERS and WF_ROLES, that tracks how assignments of users to roles are made directly or inherited through role hierarchy relationships. The view shows only currently active assignments.

The WF_USER_ROLE_ASSIGNMENTS_V view contains the following columns:

WF_ALL_ROLES_VL

The WF_ALL_ROLES_VL view contains role information similar to the WF_ROLES view. However, WF_ALL_ROLES_VL includes all roles, whether not yet valid, currently valid, or expired.

The WF_ALL_ROLES_VL view contains the following columns:

WF_ALL_USER_ROLES

The WF_ALL_USER_ROLES view contains user/role association information similar to the WF_USER_ROLES view. However, WF_ALL_USER_ROLES includes all user/role associations, whether not yet valid, currently valid, or expired.

The WF_ALL_USER_ROLES view contains the following columns:

WF_ALL_USER_ROLE_ASSIGNMENTS

The WF_ALL_USER_ROLE_ASSIGNMENTS view contains information about how assignments of users to roles are made directly or inherited through role hierarchy relationships, similar to the WF_USER_ROLE_ASSIGNMENTS_V view. However, WF_ALL_USER_ROLE_ASSIGNMENTS includes all user/role assignments, whether not yet valid, currently valid, or expired.

The WF_ALL_USER_ROLE_ASSIGNMENTS view contains the following columns: