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

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.

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.

• description

• preferredLanguage

• orclNLSTerritory

• mail

• FacsimileTelephoneNumber

• ExpirationDate

• orclWFParentOrigSys

• orclWFParentOrigSysID

• OWNER_TAG

• LAST_UPDATED_BY

• LAST_UPDATE_DATE

• LAST_UPDATE_LOGIN

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.

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.

• 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 three additional special attributes that you can use to specify how the role information should be modified.

• DELETE - You can use this attribute when you want to remove a role from availability to participate in a workflow. If you include this attribute with a value of 'TRUE', the expiration date for the role 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 role 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 role for which a record already exists in WF_LOCAL_ROLES. If you include this attribute with a value of 'TRUE', the Propagate_Role() 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 role, 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 role record already exists in WF_LOCAL_ROLES.

  Note: If an Oracle Human Resources person role with an originating system of PER_ROLE is propagated using Propagate_Role(), and that person is linked to an Oracle E-Business Suite user, then the procedure updates the corresponding user record with an originating system of PER in WF_LOCAL_ROLES, as well as the person record.

• WFSYNCH_OVERWRITE_USERROLES - By default, when you propagate a change to an existing role with the Propagate_Role() API, Oracle Workflow updates only the corresponding record in the WF_LOCAL_ROLES table. You can use the WFSYNCH_OVERWRITE_USERROLES attribute to specify that Oracle Workflow should also update the standard Who columns LAST_UPDATED_BY, LAST_UPDATE_DATE, and LAST_UPDATE_LOGIN for the related associations of users and roles in the WF_LOCAL_USER_ROLES table and for the related assignments of users to roles in the WF_USER_ROLE_ASSIGNMENTS table. In this way you can mark the records in these tables as being affected by the change to the role information if you need to do so for audit purposes.

  If you want to update the standard Who columns for the related records in WF_LOCAL_USER_ROLES and WF_USER_ROLE_ASSIGNMENTS in addition to WF_LOCAL_ROLES, add the WFSYNCH_OVERWRITE_USERROLES attribute with the value TRUE to the attribute list that you will pass in the p_attributes parameter for the Propagate_Role() API.

  Note: Ensure that you also include the [LAST_UPDATED_BY], [LAST_UPDATE_DATE], and [LAST_UPDATE_LOGIN] attributes in the list with the values you want to set. If you do not provide values for these attributes, Oracle Workflow does not update the standard Who columns in WF_LOCAL_USER_ROLES and WF_USER_ROLE_ASSIGNMENTS, even if you set the WFSYNCH_OVERWRITE_USERROLES attribute to TRUE.

  If you do not want to update the standard Who columns for the related records in WF_LOCAL_USER_ROLES and WF_USER_ROLE_ASSIGNMENTS, then set the value of the WFSYNCH_OVERWRITE_USERROLES attribute to FALSE, or simply omit this attribute from the list. In this case Oracle Workflow updates the standard Who columns only for this role record in the WF_LOCAL_ROLES table.

Arguments (input)