Previous	Next		Contents	Index	Glossary

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.

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.

• description

• preferredLanguage

• orclNLSTerritory

• mail

• FacsimileTelephoneNumber

• ExpirationDate

• orclWFParentOrigSys

• orclWFParentOrigSysID

• OWNER_TAG

• LAST_UPDATED_BY

• LAST_UPDATE_DATE

• LAST_UPDATE_LOGIN

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.

• The originating system and originating system ID values that are passed as parameters to the procedure override any originating system and originating system ID values that are provided as attributes within the attribute list, if these values differ.

• Likewise, if an expiration date value is passed as a parameter to the procedure, that value overrides any expiration date value provided as an attribute within the attribute list. However, if the p_expiration_date parameter is null, the value of the ExpirationDate attribute will be used, if one is provided. You must provide the ExpirationDate attribute value in the following format:

		to_char(<your date variable>, WF_ENGINE.Date_Format)

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

• DELETE - You can use this attribute when you want to remove a user from availability to participate in a workflow. If you include this attribute with a value of 'TRUE', the expiration date for the user in WF_LOCAL_ROLES is set to sysdate and the status is set to INACTIVE.

Note: If you also pass a value for the p_expiration_date parameter, however, that value will override the DELETE attribute. Additionally, if the p_expiration_date parameter is null but you include the ExpirationDate attribute, that attribute value will override the DELETE attribute. In these cases the user will remain valid and active until the specified expiration date.

• UpdateOnly - You can use this attribute for performance gain when you want to modify information for a user for whom a record already exists in WF_LOCAL_ROLES. If you include this attribute with a value of 'TRUE', the Propagate_User() API attempts to update the record directly, without first inserting the record.

If this update attempt fails because a record does not already exist for that user, the procedure will then insert the record. However, the initial unsuccessful attempt will degrade performance, so you should only use the UpdateOnly attribute when you are certain that the user record already exists in WF_LOCAL_ROLES.

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.

See Also