Skip Headers

Oracle Workflow API Reference
Release 2.6.4

Part Number B15855-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Skip Headers

Oracle Workflow API Reference
Release 2.6.4
Part Number B15855-02
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Directory Service APIs

Workflow Directory Service APIs

The following APIs can be called by an application program or a workflow function in the runtime phase to retrieve information about existing users and roles, as well as create and manage new ad hoc users and roles in the directory service. These APIs are defined in a PL/SQL package called WF_DIRECTORY.

Attention: If you implement Oracle Internet Directory integration, you must maintain your users only through Oracle Internet Directory. You must not create ad hoc users in the WF_LOCAL_ROLES table, because you risk discrepancies in your user information and unpredictable results if you use any tool other than Oracle Internet Directory to maintain users after integrating with Oracle Internet Directory. Consequently, if you implement Oracle Internet Directory integration, you must not use the CreateAdHocUser(), SetAdHocUserStatus(), SetAdHocUserExpiration(), or SetAdHocUserAttr() APIs in the WF_DIRECTORY package.

You can still use ad hoc roles, however, since Workflow roles are not maintained through Oracle Internet Directory.

Some directory service APIs use PL/SQL table composite datatypes defined in the WF_DIRECTORY package. The following table shows the column datatype definition for each PL/SQL table type.

PL/SQL Table Types in WF_DIRECTORY
PL/SQL Table Type Column Datatype Definition
UserTable varchar2(320)
RoleTable varchar2(320)

Related Topics

Standard API for PL/SQL Procedures Called by Function Activities, Oracle Workflow Developer's Guide

GetRoleUsers

Syntax

procedure GetRoleUsers
  (role in varchar2,
   users out wF_DIRECTORY.UserTable);

Description

Returns a table of users for a given role.

Note: A role can contain only individual users as its members. It cannot contain another role.

Arguments (input)

Variable Description
role A valid role name.

GetUserRoles

Syntax

procedure GetUserRoles
  (user in varchar2,
   roles out WF_DIRECTORY.RoleTable);

Description

Returns a table of roles that a given user is assigned to.

Arguments (input)

Variable Description
user A valid username.

GetRoleInfo

Syntax

procedure GetRoleInfo
  (Role in varchar2,
   Display_Name out varchar2,
   Email_Address out varchar2,
   Notification_Preference out varchar2,
   Language out varchar2, 
   Territory out varchar2);

Description

Returns the following information about a role:

Note: In Oracle Applications, for roles that are Oracle Applications users marked with an originating system of FND_USR or PER, the GetRoleInfo() procedure by default retrieves the language and territory values from the ICX: Language and ICX: Territory profile options for that Oracle Applications user.

However, if the WF_PREFERENCE resource token is defined and set to FND, then the GetRoleInfo() procedure obtains the language and territory values from the Oracle Workflow preferences table instead.

The WF_PREFERENCE resource token is not used in the standalone version of Oracle Workflow.

Arguments (input)

Variable Description
role A valid role name.

GetRoleInfo2

Syntax

procedure GetRoleInfo2
  (Role in varchar2,
   Role_Info_Tbl out wf_directory.wf_local_roles_tbl_type);

Description

Returns the following information about a role in a PL/SQL table:

Note: In Oracle Applications, for roles that are Oracle Applications users marked with an originating system of FND_USR or PER, the GetRoleInfo2() procedure by default retrieves the language and territory values from the ICX: Language and ICX: Territory profile options for that Oracle Applications user.

However, if the WF_PREFERENCE resource token is defined and set to FND, then the GetRoleInfo2() procedure obtains the language and territory values from the Oracle Workflow preferences table instead.

The WF_PREFERENCE resource token is not used in the standalone version of Oracle Workflow.

Arguments (input)

Variable Description
role A valid role name.

IsPerformer

Syntax

function IsPerformer
  (user in varchar2,
   role in varchar2) 
  return boolean;

Description

Returns TRUE or FALSE to identify whether a user is a performer, also known as a member, of a role.

Arguments (input)

Variable Description
user A valid username.
role A valid role name.

UserActive

Syntax

function UserActive
  (username in varchar2)
  return boolean;

Description

Determines if a user currently has a status of 'ACTIVE' and is available to participate in a workflow. Returns TRUE if the user has a status of 'ACTIVE', otherwise it returns FALSE.

Arguments (input)

Variable Description
username A valid username.

GetUserName

Syntax

procedure GetUserName
  (p_orig_system in varchar2,
   p_orig_system_id in varchar2,
   p_name out varchar2,
   p_display_name out varchar2);

Description

Returns a Workflow display name and username for a user given the system information from the original user and roles repository.

Arguments (input)

Variable Description
p_orig_system Code that identifies the original repository table.
p_orig_system_id ID of a row in the original repository table.

GetRoleName

Syntax

procedure GetRoleName
  (p_orig_system in varchar2,
   p_orig_system_id in varchar2,
   p_name out varchar2,
   p_display_name out varchar2);

Description

Returns a Workflow display name and role name for a role given the system information from the original user and roles repository.

Arguments (input)

Variable Description
p_orig_system Code that identifies the original repository table.
p_orig_system_id ID of a row in the original repository table.

GetRoleDisplayName

Syntax

function GetRoleDisplayName
  (p_role_name in varchar2)
  return varchar2;
  pragma restrict_references(GetRoleDisplayName, WNDS, WNPS);

Description

Returns a Workflow role's display name given the role's internal name.

Arguments (input)

Variable Description
p_role_name The internal name of the role.

CreateAdHocUser

Syntax

procedure CreateAdHocUser
  (name in out varchar2,
   display_name in out varchar2,
   language in varchar2 default null,
   territory in varchar2 default null,
   description in varchar2 default null,
   notification_preference in varchar2 default 'MAILHTML',
   email_address in varchar2 default null,
   fax in varchar2 default null,
   status in varchar2 default 'ACTIVE',
   expiration_date in date default null,
   parent_orig_system in varchar2 default null,
   parent_orig_system_id in number default null);

Description

Creates a user at runtime by creating a value in the WF_LOCAL_ROLES table with the user flag set to Y. This is referred to as an ad hoc user.

Attention: If you implement Oracle Internet Directory integration for standalone Oracle Workflow, you must maintain your users only through Oracle Internet Directory. You must not use the CreateAdHocUser() API to create new users in the WF_LOCAL_ROLES table, because you risk discrepancies in your user information and unpredictable results if you use any tool other than Oracle Internet Directory to maintain users after integrating with Oracle Internet Directory.

Arguments (input)

Variable Description
name An internal name for the user. The internal name must be no longer than 320 characters. It is recommended that the internal name be all uppercase. This procedure checks that the name provided does not already exist in WF_USERS and returns an error if the name already exists. If you do not provide an internal name, the system generates an internal name for you where the name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
display_name The display name of the user. This procedure checks that the display name provided does not already exist in WF_USERS and returns an error if the display name already exists. If you do not provide a display name, the system generates one for you where the display name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
language The value of the database NLS_LANGUAGE initialization parameter that specifies the default language-dependent behavior of the user's notification session. If null, the procedure resolves this to the language setting of your current session.
territory The value of the database NLS_TERRITORY initialization parameter that specifies the default territory-dependent date and numeric formatting used in the user's notification session. If null, the procedure resolves this to the territory setting of your current session.
description An optional description for the user.
notification_preference Indicate how this user prefers to receive notifications: 'MAILTEXT', 'MAILHTML', 'MAILATTH', 'MAILHTM2', 'QUERY', 'SUMMARY', or, for Oracle Applications only, 'SUMHTML'. If null, the procedure sets the notification preference to 'MAILHTML'.
email_address A optional electronic mail address for this user.
fax An optional fax number for the user.
status The availability of the user to participate in a workflow process. The possible statuses are 'ACTIVE', 'EXTLEAVE', 'INACTIVE', and 'TMPLEAVE'. If null, the procedure sets the status to 'ACTIVE'.
expiration_date The date at which the user is no longer valid in the directory service.
parent_orig_system An optional code for the originating system of an entity that you want to mark as being related to this user.
parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.

Related Topics

Setting Up an Oracle Workflow Directory Service, Oracle Workflow Administrator's Guide

CreateAdHocRole

Syntax

procedure CreateAdHocRole
  (role_name in out varchar2,
   role_display_name in out varchar2,
   language in varchar2 default null,
   territory in varchar2 default null,
   role_description in varchar2 default null,
   notification_preference in varchar2 default 'MAILHTML',
   role_users in varchar2 default null,
   email_address in varchar2 default null,
   fax in varchar2 default null,
   status in varchar2 default 'ACTIVE',
   expiration_date in date default null, 
   parent_orig_system in varchar2 default null,
   parent_orig_system_id in number default null,
   owner_tag in varchar2 default null);

Description

Creates a role at runtime by creating a value in the WF_LOCAL_ROLES table with the user flag set to N. This is referred to as an ad hoc role.

Note: A role can contain only individual users as its members. It cannot contain another role.

Arguments (input)

Variable Description
role_name An internal name for the role. The internal name must be no longer than 320 characters. It is recommended that the internal name be all uppercase. This procedure checks that the name provided does not already exist in WF_ROLES and returns an error if the name already exists. If you do not provide an internal name, the system generates an internal name for you where the name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
role_display_name The display name of the role. This procedure checks that the display name provided does not already exist in WF_ROLES and returns an error if the display name already exists. If you do not provide a display name, the system generates one for you where the display name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
language The value of the database NLS_LANGUAGE initialization parameter that specifies the default language-dependent behavior of the user's notification session. If null, the procedure resolves this to the language setting of your current session.
territory The value of the database NLS_TERRITORY initialization parameter that specifies the default territory-dependent date and numeric formatting used in the user's notification session. If null, the procedure resolves this to the territory setting of your current session.
role_description An optional description for the role.
notification_preference Indicate how this role receives notifications: 'MAILTEXT', 'MAILHTML', 'MAILATTH', 'MAILHTM2', 'QUERY', 'SUMMARY', or, for Oracle Applications only, 'SUMHTML'. If null, the procedure sets the notification preference to 'MAILHTML'.
role_users Indicate the names of the users that belong to this role, using commas or spaces to delimit the list.
email_address A optional electronic mail address for this role or a mail distribution list defined by your electronic mail system.
fax An optional fax number for the role.
status The availability of the role to participate in a workflow process. The possible statuses are ACTIVE, EXTLEAVE, INACTIVE, and TMPLEAVE. If null, the procedure sets the status to 'ACTIVE'.
expiration_date The date at which the role is no longer valid in the directory service.
parent_orig_system An optional code for the originating system of an entity that you want to mark as being related to this role.
parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.
owner_tag A code to identify the program or application that owns the information for this role.

Related Topics

Setting Up an Oracle Workflow Directory Service, Oracle Workflow Administrator's Guide

CreateAdHocRole2

Syntax

procedure CreateAdHocRole2
  (role_name in out varchar2,
   role_display_name in out varchar2,
   language in varchar2 default null,
   territory in varchar2 default null,
   role_description in varchar2 default null,
   notification_preference in varchar2 default 'MAILHTML',
   role_users in WF_DIRECTORY.UserTable,
   email_address in varchar2 default null,
   fax in varchar2 default null,
   status in varchar2 default 'ACTIVE',
   expiration_date in date default null, 
   parent_orig_system in varchar2 default null,
   parent_orig_system_id in number default null,
   owner_tag in varchar2 default null);

Description

Creates a role at runtime by creating a value in the WF_LOCAL_ROLES table with the user flag set to N. This is referred to as an ad hoc role. CreateAdHocRole2() accepts the list of users who belong to the role in the WF_DIRECTORY.UserTable format, which lets you include user names that contain spaces or commas.

Note: A role can contain only individual users as its members. It cannot contain another role.

Arguments (input)

Variable Description
role_name An internal name for the role. The internal name must be no longer than 320 characters. It is recommended that the internal name be all uppercase. This procedure checks that the name provided does not already exist in WF_ROLES and returns an error if the name already exists. If you do not provide an internal name, the system generates an internal name for you where the name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
role_display_name The display name of the role. This procedure checks that the display name provided does not already exist in WF_ROLES and returns an error if the display name already exists. If you do not provide a display name, the system generates one for you where the display name contains a prefix of '~WF_ADHOC-' followed by a sequence number.
language The value of the database NLS_LANGUAGE initialization parameter that specifies the default language-dependent behavior of the user's notification session. If null, the procedure resolves this to the language setting of your current session.
territory The value of the database NLS_TERRITORY initialization parameter that specifies the default territory-dependent date and numeric formatting used in the user's notification session. If null, the procedure resolves this to the territory setting of your current session.
role_description An optional description for the role.
notification_preference Indicate how this role receives notifications: 'MAILTEXT', 'MAILHTML', 'MAILATTH', 'MAILHTM2', 'QUERY', 'SUMMARY', or, for Oracle Applications only, 'SUMHTML'. If null, the procedure sets the notification preference to 'MAILHTML'.
role_users The names of the users that belong to this role, as a table in the WF_DIRECTORY.UserTable format.
email_address A optional electronic mail address for this role or a mail distribution list defined by your electronic mail system.
fax An optional fax number for the role.
status The availability of the role to participate in a workflow process. The possible statuses are ACTIVE, EXTLEAVE, INACTIVE, and TMPLEAVE. If null, the procedure sets the status to 'ACTIVE'.
expiration_date The date at which the role is no longer valid in the directory service.
parent_orig_system An optional code for the originating system of an entity that you want to mark as being related to this role.
parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.
owner_tag A code to identify the program or application that owns the information for this role.

Related Topics

Setting Up an Oracle Workflow Directory Service, Oracle Workflow Administrator's Guide

AddUsersToAdHocRole

Syntax

procedure AddUsersToAdHocRole
  (role_name in varchar2,
   role_users in varchar2);

Description

Adds users to an existing ad hoc role.

Note: A role can contain only individual users as its members. It cannot contain another role.

Arguments (input)

Variable Description
role_name The internal name of the ad hoc role.
role_users The list of users, delimited by spaces or commas. Users can be ad hoc users or users defined in an application, but they must already be defined in the Oracle Workflow directory service.

AddUsersToAdHocRole2

Syntax

procedure AddUsersToAdHocRole2
  (role_name in varchar2,
   role_users in WF_DIRECTORY.UserTable);

Description

Adds users to a existing ad hoc role. AddUsersToAdHocRole2() accepts the list of users in the WF_DIRECTORY.UserTable format, which lets you include user names that contain spaces or commas.

Note: A role can contain only individual users as its members. It cannot contain another role.

Arguments (input)

Variable Description
role_name The internal name of the ad hoc role.
role_users The list of users, as a table in the WF_DIRECTORY.UserTable format. Users can be ad hoc users or users defined in an application, but they must already be defined in the Oracle Workflow directory service.

RemoveUsersFromAdHocRole

Syntax

procedure RemoveUsersFromAdHocRole
  (role_name in varchar2,
   role_users in varchar2 default null);

Description

Removes users from an existing ad hoc role.

Arguments (input)

Variable Description
role_name The internal name of the ad hoc role.
role_users List of users to remove from the ad hoc role. The users are delimited by commas or spaces. If null, all users are removed from the role.

SetAdHocUserStatus

Syntax

procedure SetAdHocUserStatus
  (user_name in varchar2,
   status in varchar2 default 'ACTIVE');

Description

Sets the status of an ad hoc user as 'ACTIVE' or 'INACTIVE'.

Attention: If you implement Oracle Internet Directory integration, you must maintain your users only through Oracle Internet Directory. You must not use the SetAdHocUserStatus() API to update user information in the WF_LOCAL_ROLES table, because you risk discrepancies in your user information and unpredictable results if you use any tool other than Oracle Internet Directory to maintain users after integrating with Oracle Internet Directory.

Arguments (input)

Variable Description
user_name The internal name of the user.
status A status of 'ACTIVE' or 'INACTIVE' to set for the user. If null, the status is 'ACTIVE'.

SetAdHocRoleStatus

Syntax

procedure SetAdHocRoleStatus
  (role_name in varchar2,
   status in varchar2 default 'ACTIVE');

Description

Sets the status of an ad hoc role as 'ACTIVE' or 'INACTIVE'.

Arguments (input)

Variable Description
role_name The internal name of the role.
status A status of 'ACTIVE' or 'INACTIVE' to set for the role. If null, the status is 'ACTIVE'.

SetAdHocUserExpiration

Syntax

procedure SetAdHocUserExpiration 
  (user_name in varchar2,
   expiration_date in date default sysdate);

Description

Updates the expiration date for an ad hoc user.

Note that although users and roles whose expiration date has passed do not appear in the seeded WF_USERS, WF_ROLES, and WF_USER_ROLES views, they are not removed from the Workflow local tables until you purge them using Directory(). You should periodically purge expired users and roles in order to improve performance. See: Directory.

Attention: If you implement Oracle Internet Directory integration, you must maintain your users only through Oracle Internet Directory. You must not use the SetAdHocUserExpiration() API to update user information in the WF_LOCAL_ROLES table, because you risk discrepancies in your user information and unpredictable results if you use any tool other than Oracle Internet Directory to maintain users after integrating with Oracle Internet Directory.

Arguments (input)

Variable Description
user_name The internal name of the ad hoc user.
expiration_date New expiration date. If null, the procedure defaults the expiration date to sysdate.

SetAdHocRoleExpiration

Syntax

procedure SetAdHocRoleExpiration
  (role_name in varchar2,
   expiration_date in date default sysdate);

Description

Updates the expiration date for an ad hoc role.

Note that although users and roles whose expiration date has passed do not appear in the seeded WF_USERS, WF_ROLES, and WF_USER_ROLES views, they are not removed from the Workflow local tables until you purge them using Directory(). You should periodically purge expired users and roles in order to improve performance. See: Directory.

Arguments (input)

Variable Description
role_name The internal name of the ad hoc role.
expiration_date New expiration date. If null, the procedure defaults the expiration date to sysdate.

SetAdHocUserAttr

Syntax

procedure SetAdHocUserAttr
  (user_name in varchar2,
   display_name in varchar2 default null,
   notification_preference in varchar2 default null,
   language in varchar2 default null,
   territory in varchar2 default null,
   email_address in varchar2 default null,
   fax in varchar2 default null, 
   parent_orig_system in varchar2 default null,
   parent_orig_system_id in number default null,
   owner_tag in varchar2 default null);

Description

Updates the attributes for an ad hoc user.

Attention: If you implement Oracle Internet Directory integration, you must maintain your users only through Oracle Internet Directory. You must not use the SetAdHocUserAttr() API to update user information in the WF_LOCAL_ROLES table, because you risk discrepancies in your user information and unpredictable results if you use any tool other than Oracle Internet Directory to maintain users after integrating with Oracle Internet Directory.

Arguments (input)

Variable Description
user_name The internal name of the ad hoc user to update.
display_name A new display name for the ad hoc user. If null, the display name is not updated.
notification_preference A new notification preference of 'MAILTEXT', 'MAILHTML', 'MAILATTH', 'MAILHTM2', 'QUERY', 'SUMMARY', or, for Oracle Applications only, 'SUMHTML'. If null, the notification preference is not updated.
language A new value of the database NLS_LANGUAGE initialization parameter for the ad hoc user. If null, the language setting is not updated.
territory A new value of the database NLS_TERRITORY initialization parameter for the ad hoc user. If null, the territory setting is not updated.
email_address A new valid electronic mail address for the ad hoc user. If null, the electronic mail address is not updated.
fax A new fax number for the ad hoc user. If null, the fax number is not updated.
parent_orig_system An optional code for the originating system of an entity that you want to mark as being related to this user.
parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.
owner_tag A code to identify the program or application that owns the information for this user.

SetAdHocRoleAttr

Syntax

procedure SetAdHocRoleAttr
  (role_name in varchar2,
   display_name in varchar2 default null,
   notification_preference in varchar2 default null,
   language in varchar2 default null,
   territory in varchar2 default null,
   email_address in varchar2 default null,
   fax in varchar2 default null, 
   parent_orig_system in varchar2 default null,
   parent_orig_system_id in number default null,
   owner_tag in varchar2 default null);

Description

Updates the attributes for an ad hoc role.

Arguments (input)

Variable Description
role_name The internal name of the ad hoc role to update.
display_name A new display name for the ad hoc role. If null, the display name is not updated.
notification_preference A new notification preference of 'MAILTEXT', 'MAILHTML', 'MAILATTH', 'MAILHTM2', 'QUERY', 'SUMMARY', or, for Oracle Applications only, 'SUMHTML'. If null, the notification preference is not updated.
language A new value of the database NLS_LANGUAGE initialization parameter for the ad hoc role. If null, the language setting is not updated.
territory A new value of the database NLS_TERRITORY initialization parameter for the ad hoc role. If null, the territory setting is not updated.
email_address A new valid electronic mail address for the ad hoc role. If null, the electronic mail address is not updated.
fax A new fax number for the ad hoc role. If null, the fax number is not updated.
parent_orig_system An optional code for the originating system of an entity that you want to mark as being related to this role.
parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.
owner_tag A code to identify the program or application that owns the information for this role.

ChangeLocalUserName

Syntax

function ChangeLocalUserName
  (OldName in varchar2,
   NewName in varchar2,
   Propagate in boolean default TRUE)
  return boolean;

Description

Changes a user's name in the WF_LOCAL_ROLES table. Returns TRUE if the name change completes successfully; otherwise, the API returns FALSE.

Arguments (input)

Variable Description
OldName The current name of the user.
NewName The new name for the user.
Propagate Specify TRUE to change all occurrences of the old user name to the new user name.

IsMLSEnabled

Syntax

function IsMLSEnabled
  (p_orig_system in varchar2)
  return boolean;

Description

Determines whether Multilingual Support (MLS) is enabled for the specified originating system. Returns TRUE if MLS is enabled; otherwise the API returns FALSE.

Arguments (input)

Variable Description
p_orig_system A system from which directory service information originates.

Workflow LDAP APIs

Call the following APIs to synchronize local user information in your Workflow directory service with the users in an LDAP directory such as Oracle Internet Directory. These APIs are defined in a PL/SQL package called WF_LDAP.

Related Topics

Synchronizing Workflow Directory Services with Oracle Internet Directory, Oracle Workflow Administrator's Guide

Synch_changes

Syntax

function synch_changes 
  return boolean;

Description

Determines whether there have been any user changes to an LDAP directory since the last synchronization by querying the LDAP change log records; if there are any changes, including creation, modification, and deletion, Synch_changes() stores the user attribute information in an attribute cache and raises the oracle.apps.global.user.change event to alert interested parties. The function connects to the LDAP directory specified in the global workflow preferences. One event is raised for each changed user.

If the function completes successfully, it returns TRUE; otherwise, if it encounters an exception, it returns FALSE.

Related Topics

Synchronizing Workflow Directory Services with Oracle Internet Directory, Oracle Workflow Administrator's Guide

Setting Global User Preferences, Oracle Workflow Administrator's Guide

User Entry Has Changed Event, Oracle Workflow Developer's Guide

Synch_all

Syntax

function synch_all 
  return boolean;

Description

Retrieves all users from an LDAP directory, stores the user attribute information in an attribute cache, and raises the oracle.apps.global.user.change event to alert interested parties. The function connects to the LDAP directory specified in the global workflow preferences. One event is raised for each user.

Because Synch_all() retrieves information for all users stored in the LDAP directory, you should use this function only once during setup, or as required for recovery or cleanup. Subsequently, you can use Synch_changes() or Schedule_changes() to retrieve only changed user information.

If the function completes successfully, it returns TRUE; otherwise, if it encounters an exception, it returns FALSE.

The standalone Oracle Workflow installation runsSynch_all() to begin your Workflow directory service synchronization with Oracle Internet Directory if you implement Oracle Internet Directory integration.

Related Topics

Synchronizing Workflow Directory Services with Oracle Internet Directory, Oracle Workflow Administrator's Guide

Setting Global User Preferences, Oracle Workflow Administrator's Guide

User Entry Has Changed Event, Oracle Workflow Developer's Guide

Synch_changes

Schedule_changes

Schedule_changes

Syntax

procedure schedule_changes 
  (l_day in pls_integer default 0,
   l_hour in pls_integer default 0,
   l_minute in pls_integer default 10);

Description

Runs the Synch_changes() API repeatedly at the specified time interval to check for user changes in an LDAP directory and alert interested parties of any changes. The default interval is ten minutes. Schedule_changes() submits a database job using the DBMS_JOB utility to run Synch_changes().

Run Schedule_changes() to maintain your Workflow directory service synchronization with Oracle Internet Directory if you implement Oracle Internet Directory integration.

Arguments (input)

Variable Description
l_day The number of days in the interval to specify how often you want to run the Synch_changes() API. The default value is zero.
l_hour The number of hours in the interval to specify how often you want to run the Synch_changes() API. The default value is zero.
l_minute The number of minutes in the interval to specify how often you want to run the Synch_changes() API. The default value is ten.

Related Topics

Synchronizing Workflow Directory Services with Oracle Internet Directory, Oracle Workflow Administrator's Guide

Synch_changes

Workflow Local Synchronization APIs

The following APIs can be called in Oracle Applications to synchronize user and role information stored in application tables with the information in the Workflow local tables. These APIs are defined in a PL/SQL package called WF_LOCAL_SYNCH.

Related Topics

Setting Up an Oracle Workflow Directory Service, Oracle Workflow Administrator's Guide

Propagate_User

Syntax

procedure Propagate_User 
  (p_orig_system in varchar2,
   p_orig_system_id in number,
   p_attributes in wf_parameter_list_t,
   p_start_date in date default null,
   p_expiration_date in date default null);

Description

Synchronizes the information for a user from an application table with the WF_LOCAL_ROLES table and marks this record as an individual user by setting the user flag to Y. The user is identified by the specified originating system and originating system ID. The partition ID where the user's information is stored is set automatically depending on the originating system.

Note: For Oracle Applications, only Oracle Applications users from the FND_USER table, Oracle Trading Community Architecture (TCA) person parties, and TCA contacts (relationship parties) should be synchronized using Propagate_User(). All other Oracle Applications modules should synchronize their information using Propagate_Role().

The user information to be stored in the WF_LOCAL_ROLES table must be provided in the WF_PARAMETER_LIST_T format. You can use the WF_EVENT.AddParameterToList() API to add attributes to the list. The following table shows the attributes that should be included in the list to populate the required columns in WF_LOCAL_ROLES. The standard LDAP attribute names should be used for these attributes.

User Attributes
Database Column Attribute Name
NAME [USER_NAME]
DISPLAY_NAME [DisplayName]
DESCRIPTION [description]
NOTIFICATION_PREFERENCE [orclWorkFlowNotificationPref]
LANGUAGE [preferredLanguage]
TERRITORY [orclNLSTerritory]
EMAIL_ADDRESS [mail]
FAX [FacsimileTelephoneNumber]
STATUS [orclIsEnabled]
EXPIRATION_DATE [ExpirationDate]
ORIG_SYSTEM [orclWFOrigSystem]
ORIG_SYSTEM_ID [orclWFOrigSystemID]
PARENT_ORIG_SYSTEM [orclWFParentOrigSys]
PARENT_ORIG_SYSTEM_ID [orclWFParentOrigSysID]
OWNER_TAG [OWNER_TAG]
PERSON_PARTY_ID [PERSON_PARTY_ID]
LAST_UPDATED_BY [LAST_UPDATED_BY]
LAST_UPDATE_DATE [LAST_UPDATE_DATE]
LAST_UPDATE_LOGIN [LAST_UPDATE_LOGIN]
CREATED_BY [CREATED_BY]
CREATION_DATE [CREATION_DATE]

In normal operating mode, if any of these attributes except USER_NAME are not passed in the attribute list or are null, the existing value in the corresponding field in WF_LOCAL_ROLES remains the same. For example, if no e-mail address is passed, the existing e-mail address for the user is retained. However, you must always pass the USER_NAME attribute, because the Propagate_User() procedure uses this value in a WHERE condition and will fail if the USER_NAME is not provided. Also, if the user record does not already exist, you must pass all of the listed attributes since there are no existing values to use.

For more robust code, you should always pass all of the listed attributes when calling Propagate_User(). In this way you can avoid errors caused by trying to determine dynamically which attributes to pass.

Note: If a display name is not provided in the attribute list when the user record is first created in normal operating mode, this value is set by default to a composite value in the format <orig_system>:<orig_system_ID> in the user record in WF_LOCAL_ROLES. Additionally, if no notification preference is provided, the notification preference for the user record is set by default to MAILHTML, and if no status is provided, the status for the user record is set by default to ACTIVE. If no TCA person party ID is provided, Oracle Workflow uses a value consisting of the originating system and originating system ID as the person party ID.

You can also call Propagate_User() in overwrite mode by including a special attribute named WFSYNCH_OVERWRITE with a value of 'TRUE'. In overwrite mode, if one of the following attributes is not passed or is null, the procedure sets the value of the corresponding field in WF_LOCAL_ROLES to null, deleting the previous value.

Consequently, when you are using overwrite mode, you must pass values for all the attributes that you do not want to be null. Also, you must always pass the USER_NAME attribute.

Note: The DISPLAY_NAME, NOTIFICATION_PREFERENCE, STATUS, ORIG_SYSTEM, and ORIG_SYSTEM_ID columns in the WF_LOCAL_ROLES table have a NOT NULL constraint, so these columns retain their existing values if you do not pass a value for the corresponding attributes, even if you are using overwrite mode.

The NAME column in WF_LOCAL_ROLES also has a NOT NULL constraint, and you cannot omit the USER_NAME attribute in any case because it is required for the API.

Certain values, including the originating system, originating system ID, and expiration date, can be passed both as parameters for the Propagate_User() API and as attributes within the attribute list parameter. These values are repeated in the attribute list because Propagate_User() sends only the attribute list to the Entity Manager that coordinates LDAP integration, and not any of the procedure's other parameters.

Oracle Workflow also provides two additional special attributes that you can use to specify how the user information should be modified.

Arguments (input)

Variable Description
p_orig_system A code that you assign to the directory repository that is the source of the user information.
p_orig_system_id The primary key that identifies the user in this repository system.
p_attributes A list of attribute name and value pairs containing information about the user.
p_start_date The date at which the user becomes valid in the directory service.
p_expiration_date The date at which the user is no longer valid in the directory service.

Related Topics

AddParameterToList

Propagate_Role

Syntax

procedure Propagate_Role
  (p_orig_system in varchar2,
   p_orig_system_id in number,
   p_attributes in wf_parameter_list_t,
   p_start_date in date default null,
   p_expiration_date in date default null);

Description

Synchronizes the information for a role from an application table with the WF_LOCAL_ROLES table and sets the user flag for the role to N. The role is identified by the specified originating system and originating system ID. The partition ID where the role's information is stored is set automatically depending on the originating system.

The role information to be stored in the WF_LOCAL_ROLES table must be provided in the WF_PARAMETER_LIST_T format. You can use the WF_EVENT.AddParameterToList() API to add attributes to the list. The following table shows the attributes that should be included in the list to populate the required columns in WF_LOCAL_ROLES. The standard LDAP attribute names should be used for these attributes.

Role Attributes
Database Column Attribute Name
NAME [USER_NAME]
DISPLAY_NAME [DisplayName]
DESCRIPTION [description]
NOTIFICATION_PREFERENCE [orclWorkFlowNotificationPref]
LANGUAGE [preferredLanguage]
TERRITORY [orclNLSTerritory]
EMAIL_ADDRESS [mail]
FAX [FacsimileTelephoneNumber]
STATUS [orclIsEnabled]
EXPIRATION_DATE [ExpirationDate]
ORIG_SYSTEM [orclWFOrigSystem]
ORIG_SYSTEM_ID [orclWFOrigSystemID]
PARENT_ORIG_SYSTEM [orclWFParentOrigSys]
PARENT_ORIG_SYSTEM_ID [orclWFParentOrigSysID]
OWNER_TAG [OWNER_TAG]
LAST_UPDATED_BY [LAST_UPDATED_BY]
LAST_UPDATE_DATE [LAST_UPDATE_DATE]
LAST_UPDATE_LOGIN [LAST_UPDATE_LOGIN]
CREATED_BY [CREATED_BY]
CREATION_DATE [CREATION_DATE]

In normal operating mode, if any of these attributes except USER_NAME are not passed in the attribute list or are null, the existing value in the corresponding field in WF_LOCAL_ROLES remains the same. For example, if no e-mail address is passed, the existing e-mail address for the role is retained. However, you must always pass the USER_NAME attribute, because the Propagate_Role() procedure uses this value in a WHERE condition and will fail if the USER_NAME is not provided. Also, if the user record does not already exist, you must pass all of the listed attributes since there are no existing values to use.

For more robust code, you should always pass all of the listed attributes when calling Propagate_Role(). In this way you can avoid errors caused by trying to determine dynamically which attributes to pass.

Note: If a display name is not provided in the attribute list when the role record is first created in normal operating mode, this value is set by default to a composite value in the format <orig_system>:<orig_system_ID> in the role record in WF_LOCAL_ROLES. Additionally, if no notification preference is provided, the notification preference for the role record is set by default to MAILHTML, and if no status is provided, the status for the role record is set by default to ACTIVE.

You can also call Propagate_Role() in overwrite mode by including a special attribute named WFSYNCH_OVERWRITE with a value of 'TRUE'. In overwrite mode, if one of the following attributes is not passed or is null, the procedure sets the value of the corresponding field in WF_LOCAL_ROLES to null, deleting the previous value.

Consequently, when you are using overwrite mode, you must pass values for all the attributes that you do not want to be null. Also, you must always pass the USER_NAME attribute.

Note: The DISPLAY_NAME, NOTIFICATION_PREFERENCE, STATUS, ORIG_SYSTEM, and ORIG_SYSTEM_ID columns in the WF_LOCAL_ROLES table have a NOT NULL constraint, so these columns retain their existing values if you do not pass a value for the corresponding attributes, even if you are using overwrite mode.

The NAME column in WF_LOCAL_ROLES also has a NOT NULL constraint, and you cannot omit the USER_NAME attribute in any case because it is required for the API.

Certain values, including the originating system, originating system ID, and expiration date, can be passed both as parameters for the Propagate_Role() API and as attributes within the attribute list parameter. These values are repeated in the attribute list because Propagate_Role() sends only the attribute list to the Entity Manager that coordinates LDAP integration, and not any of the procedure's other parameters.

Oracle Workflow also provides two additional special attributes that you can use to specify how the role information should be modified.

Arguments (input)

Variable Description
p_orig_system A code that you assign to the directory repository that is the source of the role information.
p_orig_system_id The primary key that identifies the role in this repository system.
p_attributes A list of attribute name and value pairs containing information about the role.
p_start_date The date at which the role becomes valid in the directory service.
p_expiration_date The date at which the role is no longer valid in the directory service.

Related Topics

AddParameterToList

PropagateUserRole

Syntax

procedure PropagateUserRole 
  (p_user_name in varchar2,
   p_role_name in varchar2,
   p_user_orig_system in varchar2 default null,
   p_user_orig_system_id in number default null,
   p_role_orig_system in varchar2 default null,
   p_role_orig_system_id in number default null,
   p_start_date in date default null, 
   p_expiration_date in date default null, 
   p_overwrite in boolean default FALSE, 
   p_raiseErrors in boolean default FALSE,
   p_parent_orig_system in varchar2 default null,
   p_parent_orig_system_id in varchar2 default null,
   p_ownerTag in varchar2 default null,
   p_createdBy in number default null,
   p_lastUpdatedBy in number default null,
   p_lastUpdateLogin in number default null,
   p_creationDate in date default null,
   p_lastUpdateDate in date default null);

Description

Synchronizes the information for an association of a user and a role from an application table with the WF_LOCAL_USER_ROLES table.

Arguments (input)

Variable Description
p_user_name The internal name of the user.
p_role_name The internal name of the role.
p_user_orig_system A code that you assign to the directory repository that is the source of the user information.
p_user_orig_system_id The primary key that identifies the user in this repository system.
p_role_orig_system A code that you assign to the directory repository that is the source of the role information.
p_role_orig_system_id The primary key that identifies the role in this repository system.
p_start_date The date at which the association of this user with this role becomes valid in the directory service.
p_expiration_date The date at which the association of this user with this role is no longer valid in the directory service.
p_overwrite Specify TRUE or FALSE to determine whether to propagate the information in overwrite mode. In overwrite mode, if any attribute is not passed or is null, the procedure sets the value of the corresponding field in WF_LOCAL_USER_ROLES to null, deleting the previous value.

Note: Overwrite mode does not affect the user name and role name attributes. You must pass values for these parameters, because they are required for this procedure, and because the USER_NAME and ROLE_NAME columns in the WF_LOCAL_USER_ROLES table have a NOT NULL constraint.

p_raiseErrors Specify TRUE or FALSE to determine whether the procedure should raise an exception if it encounters an error.
p_parent_orig_system A code for the originating system of an entity that you want to mark as being related to the association of this user with this role.
p_parent_orig_system_id The primary key that identifies the parent entity in the parent originating system.
p_ownerTag A code to identify the program or application that owns the information for the association of this user with this role.
p_createdBy Standard Who column.
p_lastUpdatedBy Standard Who column.
p_lastUpdateLogin Standard Who column.
p_creationDate Standard Who column.
p_lastUpdateDate Standard Who column.

Workflow Role Hierarchy APIs

The following APIs can be called by an application program or a workflow function in the runtime phase to manage role hierarchy relationships in the Oracle E-Business Suite directory service. These APIs are defined in a PL/SQL package called WF_ROLE_HIERARCHY.

Related Topics

Setting Up an Oracle Workflow Directory Service, Oracle Workflow Administrator's Guide

AddRelationship

Syntax

function AddRelationship  
  (p_sub_name in varchar2,
   p_super_name in varchar2,
   p_deferMode in boolean default FALSE,
   p_enabled in varchar2 default 'Y')
  return number;

Description

Creates a hierarchical relationship between two roles in the WF_ROLE_HIERARCHIES table and returns the relationship ID.

Arguments (input)

Variable Description
p_sub_name The internal name of the subordinate role.
p_super_name The internal name of the superior role.
p_deferMode Specify TRUE or FALSE to determine whether to defer propagation of the new relationship. If you specify FALSE, existing user and role assignments are updated according to the new relationship, without deferral.
p_enabled Specify 'Y' if the relationship is initially enabled or 'N' if the relationship is initially disabled.

ExpireRelationship

Syntax

function ExpireRelationship 
  (p_sub_name in varchar2,
   p_super_name in varchar2,
   p_defer_mode in boolean default FALSE)
  return number;

Description

Expires a hierarchical relationship between two roles in the WF_ROLE_HIERARCHIES table and returns the relationship ID.

Arguments (input)

Variable Description
p_sub_name The internal name of the subordinate role.
p_super_name The internal name of the superior role.
p_defer_mode Specify TRUE or FALSE to determine whether to defer propagation of the expired relationship. If you specify FALSE, existing user and role assignments are updated according to the expired relationship, without deferral.

GetRelationships

Syntax

procedure GetRelationships
  (p_name in varchar2, 
   p_superiors out WF_ROLE_HIERARCHY.relTAB, 
   p_subordinates out WF_ROLE_HIERARCHY.relTAB, 
   p_direction in VARCHAR2 default 'BOTH');

Description

Retrieves the hierarchical relationships for the specified role and returns a table of superior roles and a table of subordinate roles. GetRelationships() stops retrieving relationships in a hierarchy when it encounters a disabled relationship.

Arguments (input)

Variable Description
p_name The internal name of the role.
p_direction Specify 'SUPERIORS' to retrieve superior roles for this role, 'SUBORDINATES' to retrieve subordinate roles for this role, or 'BOTH' to retrieve both superior and subordinate roles.

GetAllRelationships

Syntax

procedure GetAllRelationships 
  (p_name in varchar2, 
   p_superiors out WF_ROLE_HIERARCHY.relTAB, 
   p_subordinates out WF_ROLE_HIERARCHY.relTAB, 
   p_direction in VARCHAR2 default 'BOTH');

Description

Retrieves the hierarchical relationships for the specified role and returns a table of superior roles and a table of subordinate roles. GetAllRelationships() retrieves all hierarchical relationships, whether they are enabled or disabled.

Arguments (input)

Variable Description
p_name The internal name of the role.
p_direction Specify 'SUPERIORS' to retrieve superior roles for this role, 'SUBORDINATES' to retrieve subordinate roles for this role, or 'BOTH' to retrieve both superior and subordinate roles.

Workflow Preferences API

Call the following API to retrieve user preference information. The API is defined in the PL/SQL package called WF_PREF.

get_pref

Syntax

function get_pref 
  (p_user_name in varchar2,
   p_preference_name in varchar2)
  return varchar2;

Description

Retrieves the value of the specified preference for the specified user.

Arguments (input)

Variable Description
p_user_name The internal name of the user. To retrieve the value for a global preference, specify the user as -WF_DEFAULT-.
p_preference_name The name of the user preference whose value you wish to retrieve. Valid preference names are:
  • LANGUAGE

  • TERRITORY

  • MAILTYPE

  • DMHOME

  • DATEFORMAT