Tuesday, November 9, 2010

Adding External Users as Document Reviewers – Advanced Workflow Features part II

Most enterprises today use directory services for organizing users, resources, services and other objects of the heterogeneous enterprise. LDAPs are the authentication and authorization source for the various enterprise applications.

Oracle UCM can leverage these enterprise LDAPs by configuring security providers. The users in LDAP providers are identified as EXTERNAL users by the UCM. UCM queries its internal security tables to see if a user exists and if a user does not exist then queries LDAP provider for security information.

Troy Allen, in his blog on Getting User Information - Advanced Workflow Features, provides a good insight into dynamically adding users to workflow using events. Things get little different when the users are not LOCAL users within the UCM security tables but are defined externally in an LDAP. The Oracle UCM USERSECURITYATTRIBUTES table (reference http://senasystems.blogspot.com/2010_09_01_archive.html) holds user role information only for local users. External user roles are not stored in this table.

Below is an amendment to the Getting User Information - Advanced Workflow Features blog where the users are external.

Situation: An administrator wants to create a workflow where the participating users are external users and are dynamically derived based upon particular Security Role that users belong to.

Issue: UCM does not store role information of external users.
Solution: Depending on the user requirements there are two approaches to this. Solution 1 should be adopted when the latest user and role information is required. Solution 2 should be adopted when the latest user and role information is not critical but performance is.

Solution 1
Create a custom component and retrieve user information from LDAP using a Java Service Handler. Invoke this service from the workflow entry event script. This approach provides latest up to date information however has performance impact as every document workflow item will retrieve user information from the LDAP.

Solution 2
In UCM provider configuration, you can map LDAP user attributes to UCM user attributes. UCM creates or updates an entry in the “USERS” table every time an external user logs into UCM. The mapped attributes are also stored in the “USERS” table during this process. This feature comes handy when creating advanced workflow that needs to add reviewers at run time based on user role information.

A field that carries user role information can be mapped to a UCM user attribute field and during the workflow event this mapped user attribute can be queried to determine if the user should participate in the workflow or not.

Let’s go into details of Solution 2.

  1. Add a Custom User Attribute:
    Launch User Admin applet and click on Information Fields tab.


    Click on Add to add a custom User Attribute. Enter the name of the field “UserRole”. Set appropriate flags on this screen as you would like. Ideally this should be a “view only Field” since it is managed under LDAP administration.



  2. Map LDAP Attribute to User Attribute:

    I. Create a LDAP Provider
    Launch providers page under Administration > Providers and create an LDAP provider. Use information below to create provider and map LDAP attributes to user attributes.



    This is the basic LDAP provider set up screen. Key information you need is
    LDAP server – Where is the LDAP server?
    Suffix – What is the root dn of user and group information?
    LDAP Port – 389 in most of the cases but change it based on LDAP configuration.

    II. Map User Role Information
    Add appropriate group mapping to either “cn=” or check the “Use Full Group Names” checkbox to provide full dn of the groups node.


    Note: “cn=” should be based on your directory structure and the value you have entered for “LDAP Suffix”.

    Tip: Roles defined in LDAP must exist in UCM with the same name.

    III. Map User Attributes
    Under the attribute map section, you can map ldap attribute to user attribute. Add LDAP attribute as “userrole”, select newly created user attribute under User Attribute option list and click on “Add” button.


    Note: You need to restart the server for the provider changes to take effect.

  3. Create a Custom Component
    Create a custom component that can read this user attribute and make the user role information available to the workflow entry event.

    Again, Troy Allen’s blog Getting User Information - Advanced Workflow Features provides very detailed information on how to create this component so we will not go in much detail here but only highlight the changes required.

    Add a new query to the Workflow_Example component with ID “qgetusersandmappedroles”. Add query text as “select dname, uUserRole from users”.

    (Note: The custom user attribute gets added to the Users table so we can easily fetch the same from users table. All custom attributes starts with a “u”).

    Add a new Service “UserRoleMappings” that uses the new query and creates a resultset named “UserLoop”.

    Enable the component and restart the server.

  4. Change Workflow Entry Event Script
    Now that we have mapped LDAP attributes and created custom component, we are ready to modify the workflow entry event script to use the new component. Script below will run through all users in “USERS” table and add the users that belong to “REVIEWER_ROLE” role as a reviewer of the document.
    <$xuserlist=""$>
    <$xcount=0$>
    <$executeService("UserRoleMappings")$>
    <$loop UserLoop$>
      <$if uUserRole like "REVIEWER_ROLE"$>
        <$if xcount < 1$>
          <$xuserlist=dName$>
        <$else$>
          <$xtempuserlist=xuserlist$>
          <$xuserlist="" & xtempuserlist & " , " & dName$>
        <$endif$>
        <$xcount = xcount + 1$>
      <$endif$>
    <$endloop$>
    <$wfSet("xuserlist",xuserlist)$>


Test your changes

  1. Check in a document matching your workflow criteria to test the workflow.
  2. Go to Workflow Assignments to ensure the document is in the queue.
  3. From the Actions left-hand icon, click on Workflow Info. You should see all the users internal and external that were part of “REVIEWER_ROLE” role.

Points to Note:

  • If the requirement is to have all the users irrespective of their existence in “USERS” table, participate in the workflow then solution 1 is appropriate.
  • Solution 2 expects an attribute similar to userrole in user dn that carries user role information. LDAP administrator needs to set this up if it does not exist already.