Getting User Information - Advanced Workflow Features

Oracle Enterprise Content Management uses a built in Workflow tool for routing documents to individuals or groups of users for approval/rejection and editing.  While workflows can be created with predefined user participants, it is best to use Aliases or Tokens. 

·       Aliases are groups of users, managed through the ECM User Administration tool, which allows administrators to group people for a particular task or for notifications. 

·       Tokens are extremely powerful variable-like objects which administrators can use to dynamically set workflow participants.

A common use case for Tokens is in the development of AdHoc workflows.  When a user checks in a document, they can use Metadata to select an alias or user to participate in the workflow for that document.  However, tokens can be used for more advanced workflow tasks. 

Within Workflow steps, there are three levels of events that administrators can use for extended functionality and business processing of workflow logic. 

·       Entry Event is used to evaluate content conditions as the document is just entering the workflow.  For example, if a document was rejected from another step and the rejection logic routed it to this particular step, the Entry Event could test for rejection and update a metadata field.

·       Update Event is used to evaluate content actions while the document is in process of the current workflow step.  For example, if an administrator wants to automatically approve a document which is edited by a particular user during the step, this event would facilitate that.

·       Exit Event is used to evaluate content conditions as the content is leaving a particular workflow step.  For example, if an administrator wants to update a metadata field of a document as it is leaving the workflow, maybe changing a custom metadata field of xstatus to approved, this is the event where those tasks can be performed.

In some cases, Components may be required to enhance the out-of-the-box functionality of the ECM.  Components are modular programs written in IDOC script, JAVA, or a combination of the two that adds new functions to the application or enhances/alters what was originally created.  An example of a custom component might include adding an icon to Search Results if a document has an associated Discussion (See next week’s blog for an example of how to do this).

The following is an advanced example of using both Tokens and Workflow Events along with a custom Component.

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

Issue:  UCM variable like UserName, UserFullName, UserAddress, and functions like getUserValue, getValueForSpecifiedUser, isUserOverrideSet, userHasAccessToAccount, userHasGroupPrivilege, and userHasRole only retrieve information about the currently logged in user.  As the Situation statement indicates, the administrator wants to test against all users to determine which user has a specific role and add those users to the workflow step.  The desired information is not currently available in the ECM. 

Solution: In order to facilitate the request, we need to first create a new Custom Component, create a Workflow Token, and create a workflow Entry Event.

Creating the Component:

1.       Luanch the Component Wizard application and select Add from the Component List window.  Make sure the Create New Component checkbox is checked and name the Component Workflow_Example.

2.       We will create a query that will enable administrators to query against the usersecurityattributes table then provide a result set that can be looped through to find the desired users.  Click on Add and select the radio button for Query.

After clicking Next two times, we can add the Query name, calling it quserattribute (as best practice, always start query names with q). On the next screen, enter the query script and a parameter to pass into the query script: select dattributename from usersecurityattributes where dattributetype = 'role' and dusername = ?.

Click Ok to continue

Click OK to continue. 

3.       Next, you will need to create a service which calls the query and stores the information into a specific Result Set.  From the main page of the Component Wizard, click Add on the left and select Service.

Click Next two times.  Name the new service find_user and assign the DocService as the service class.

Make the Access Level Read and Scriptable.  Next click the Add button.  On the next screen, make Type equal Select cache query, Action equal quserattribute, enter NameLoop in the parameters box, and check box for check result non-empty.  Put No Data Found in the Error Message Line. 

Click OK to continue then click Finish.  When Prompted to edit, select No.

4.        Enable the component and restart the ECM server.

Creating the Token:

We will need a Workflow for our example.  In the ECM interface, go to Admin  Applets and launch Workflow Admin.  Create a new Criteria Workflow.

Once this is created, we are ready to create the Token:

1.           From the workflow menu, select Options, Token, and then click on Add.  Enter the Token Name as wk_example_token and a Description of Workflow Example Token.

2.       On the same screen, put has the following code into the Users box: <$wfAddUser(wfGet("xuserlist"), “user”)$>   

Click Ok and then Close.

To keep the example simple, we’ll create a single workflow step that uses the newly created Token to insert users who have the Role admin.

1.       With your workflow highlighted in the left hand side of the window, click Add on the right.  In the new window, put Example into the Name and Description fields.  Leave Users can review the current revision selected.  Click on Add Token and select the token you just created.

2.       Click on the Events tab.  Select the Custom Tab and click the Custom Script Expression check box.  Enter the following code: 

<$getViewValuesResultSet("docAuthors","","")$><!-- this code retreives all the known users-->

<$xuserlist=""$> <!-- this establishes the xuserlist variable with no value assigned to it-->

<$xcount=0$> <!-- it is typical to use a loop counter when trying to values and to control the looping -->

       <$loop SchemaData$> <!-- this begins the looping of the known users -->

                             <$executeService("find_user")$> <!-- this calls the service created for this example,

                                                                                                the Schemadata loop automatically assigned the parameter of dName which this service uses -->

                                           <$loop NameLoop$> <!-- this starts the loop of results from the query results in the find_user service -->

                                                          <$if strIndexOf(dAttributeName,"admin") >= 0  $> <!-- this checks for the result to see if the Role admin is there -->

                                                                        <$if xcount < 1$>  <!-- checks to see if this is the first time through the loop -->

                                                                                      <$xuserlist=dName$> <!-- assigns the variable xuserlist with the userID which has admin Role -->

                                                                        <$else$> <!-- test to see if there are more user to loop through -->

                                                                                      <$xtempuserlist=xuserlist$> <!-- creates a temp holding for all the users found so far -->

                                                                                      <$xuserlist="" & xtempuserlist & " , " & dName$> <!-- add the next user to xuserlist with a , seperator -->

                                                                        <$endif$> <!-- closes the test -->

                                                                        <$xcount = xcount + 1$> <!-- increments the loop count -->

                                                                        <$break$>

                                                          <$endif$>          

                                           <$endloop$>

       <$endloop$>

<$wfSet("xuserlist",xuserlist)$>  <!-- This applies the users to the token-->

Click OK two times and enable the workflow.

3.       Check in a document matching your workflow criteria to test the workflow.

4.       Go to Workflow Assignments to ensure the document is in the que.

5.       From the Actions left-hand icon, click on Workflow Info.  You should see all the users that matched the criteria: