Option Lists

Option lists are powerful tools we can use to improve and facilitate the check-in process for end-users. At first look, the creation and configuration can be somewhat, intimidating. In this edition of SENA Sound Bites the goal will be to reduce the fear factor from those “confusing” tables and views.

One particular function we can use for an option list is the Tree selection. It is a core piece of Folders but without the performance heavy overhead.

In our scenario, we have a very busy auto parts store and body shop. The shop manager wants the users to have the option at check-in to assign metadata such as the year, make and model of a vehicle that the shop custom fabricates specialty parts for. The shop UCM administrator armed with an arsenal of documents from the 10g and 11g document library takes on the task and hopes to have the project done in a few days. With our help we will reduce that time to a project that can be done before lunch time.

The sections that will be covered are:

Adding information fields,

Table Creation,

Adding Views,

and Relating Views for use in Option list

First let’s begin with creating our information field.

Navigate to Administration > Admin Applets > Configuration Manager > Information Fields

1) Click “Add”

2) Enter Vehicle for Field Name

3) click “OK” through next two windows

4) Click Update Database Design to commit the add field

Now we can begin creating our tables.

While still in Configuration Manager click on the Tables tab

1) Click “Create table”

1) Enter Vehicle_Year in Table Name

2) Enter Vehicle Year for Table Description

3) Add Column Name: Vehicle_Year, with type as varchar, and length 50

4) Add Column Name: Vehicle_Year_id, with type int, enable as Primary Key, and click ok twice to complete creation of table

5) Repeat steps to create remaining tables and columns below.

Table Name: Vehicle_Name

Table Description: Vehicle Name

Column Name: Vehicle_Name,

Column Type: varchar

Column Length 50

Column Name: Vehicle_Name_id,

Column Type: int

enable Primary Key check box

Column Name: Vehicle_Year_id,

Column Type: int

Table Name: Vehicle_Model

Table Description: Vehicle Model

Column Name: Vehicle_Model,

Column Type: varchar

Column Length 50

Column Name: Vehicle_Model_id,

Column Type: int

enable Primary Key check box

Column Name: Vehicle_Year_id,

Column Type: int

Column Name: Vehicle_Name_id,

Column Type: int

After table creation we can go ahead and add the views for our project

While still in Configuration Manager click on the Views tab

1) Click “Add”

2) Select Vehicle_Year table then click “Next”

3) Select all columns then click “Finish”

4) Enter “Vehicle_Year_View” for View Name, “View for vehicle year” for View Description, then click “OK”

5) Repeat steps to add views for Vehicle_Name, and Vehicle_Model.

Now that our views are added we are going to need to add the data that will be displayed for the end users.

Vehicle Year View Data:

While still in the Views section,

1) Select Vehicle_Year_View and click “Edit Values”

2) Click “Add”

3) Enter 2009 for Vehicle_Year and, 1 for Vehicle_id

4) Follow table below to complete remaining values

Vehicle Name View Data:

1) Select Vehicle_Name_View and click “Edit Values”

2) Click “Add”

3) Enter Ford for Vehicle_Name, 11 for Vehicle_Name_id, 1 for Vehicle_id, then click ok

4) Follow table below to complete remaining values

Vehicle Model View Data:

1) Select Vehicle_Model_View and select “Edit Values”

2) Click “Add”

3) Enter F-150 for Vehicle_Model, 111 for Vehicle_Model_id, 11 for Vehicle_Year_id, 1 for Vehicle_Name_id, then click ok

4) Follow table below to complete remaining values

Now that we have populated our views data we can link or relate the newly created tables.

Relations

While still in Configuration Manager click on the Relations tab

1) Click “Add”

2) Enter “Vehicle_Name_Relationship” for Relationship Name, and “Relationship for vehicle name “ for description

3) Select Vehicle_Year from the first drop-down and Vehicle_Year_id from the second drop-down in the Parent Info drop-down

4) Selec tVehicle_Name from the first drop-down and Vehicle_Year_id from the second drop-down in the Child info drop-down, then click “OK”

5) Repeat above steps to add Vehicle_Model_Relationship. In description field enter “Relationship for vehicle model” Select Vehicle_Name in the first drop-down and Vehicle_Name_id from the second drop-down for Parent Info then Vehicle_Model from the first drop-down and Vehicle_Name_id from the second drop-down for Child info

All that is now left to do is configure our field.

Field Configuration

1) Click on Information Fields and select “Vehicle” field.

2) Click "Edit"

3) Check Enable Options List

4) Click Configure

5) Check Use Tree

6) Click “Edit Definition”

7) Click drop-down to build first level of tree. Select “Vehicle_Year_View”

8) Click drop-down to build second level of tree. Select “View_Name_Relationship”

9) Click drop-down to build third level of tree. Select “View_Model_Relationship” and click “Ok” three (3) times to complete tree definition.

Our Tree option list is finally complete. To validate, we just need to go to the check in page.

In the check-in page there is a new field labeled “Vehicle”.

Click “Select” then drill down to make sure our tree displays positive results.

Now suppose the auto shop manager would rather have a dependent option list, where only information is displayed based on a previous selection.

No problem the bulk of the work is complete. All that would need to be done is:

Creation of two new information fields and,

Configuration of option list

Navigate to Administration > Admin Applets > Configuration Manager > Information Fields

1) Click “Add”

2) Enter VehicleYear for Field Name

3) Enter Vehicle Year for Field Caption

3) Check Enable Options List

4) Click Configure

5) Select Use view check-box

6) Select Vehicle_Year_View

7) Check Use Tree then click “OK” through next two windows

While still in Information Fields add the last field

1) Click “Add”

2) Enter VehicleModel for Field Name

3) Enter Vehicle Model for Field Caption

3) Check Enable Options List

4) Click Configure

5) Select Use view check-box

6) Select Vehicle_Model_View

7) Enable Dependent Field

8) Select Vehicle from Depends on field drop-down

9) Click “OK” through next two windows

10) Click Update Database Design to commit the added fields

Last step is to configure the Vehicle Information Field

1) Select Vehicle from the Information Field tab

2) Click “Configure”

3) Select Use view check-box

4) Select Vehicle_Name_View

5) Enable Dependent Field

6) Select VehicleYear from Depends on field drop-down

7) Click “OK” through next two windows

8) Refresh browser

Once again to validate changes go to check-in page and make sure the correct variables are showing.

There you have it, not one but two option lists before lunch time. This was a couple of examples of option lists, with careful planning and always on a “dev” instance first, more powerful and robust lists can be created.

Any questions or comments please reach me at lou.guerrier@senasystems.com.

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: