Validation Workflow Choosing the Assignee Based on a Metadata

This tutorial is one of the steps of a complete project tutorial on technical documentation management. Although recommended, the reading of the previous steps is not mandatory and you should be able to adapt easily the logic to your own document types.

In this tutorial we will create a one step workflow that will be assigned to a user depending on the Nature metadata of the document. Basically there will be one responsible per possible nature of the document. This workflow will set the document to approve.

Designing a workflow in the Nuxeo Platform involves several steps and can take some time; making sure you always have something functional is always a good idea. Start your workflow simple, and then enhance it, make sure you can test it along the way. You can start by creating the main path with static assignees, then add the logic to compute the assignees, then add the business logic to apply on the document (life cycle transition, version update, conversion...). And finally add the other possible paths of the workflow (loops, feedbacks...).

Creating the Workflow

To create a new workflow, simply go to the workflow section of Studio, click New and choose a name.

A workflow can be configured through four tabs:

• Definition: Where you select the name and label of the workflow.
• Variables: Where you can manage the Workflow variables that will be used through-out the different steps of the workflow, like comments, user inputs...
• Availability: Where you define the filter to enable or not the workflow.
• Graph: Where you define all the workflow steps and their transitions. This is the most important tab. After you create your workflow, it's normal you get validation error, pending the creation of the graph.

Availability Tab

First let's define when the workflow should be available.

1. Go to the Availability tab.
2. Select our previously created custom type DocumentationItem in Current document has one of the types. This makes sure the workflow can not be started on other document types.

Graph Tab

The next step is to design the graph of the workflow. So you can go to the Graph tab.

A workflow has always one (and only one) start node and at least one end node: this is the reason why you have a validation error when you create an empty workflow. On the left of the screen, you have access to all the available node types. A workflow in the Nuxeo Platform is just a list of nodes, linked together by transitions. You can see here that there are several types of Node: some of them are Tasks (assigned to users or group of users), some of them are structural (to create a branch in a workflow, to start, stop...).

Tasks are fully customizable, you can rename them, add or remove buttons and transitions. By default, you have four different user tasks, but they are all variations of a same generic user task that you can then customize.

For a start, we decided that our workflow should be as simple as possible so will just use an "Approve" task, which a simple task with one button and one transition. We will add more buttons and transitions later on if needed.

1. On the Graph tab, drag and drop a "Start" Node, a "End" Node and an "Approve" task from the left.
2. Link them by drag and dropping with your mouse the symbol of the output transition from a node to the next one as shown in the screen shot here under.
   ×
   
   Our workflow graph is now set up. The Start and Stop nodes are very simple so we do not need to do anything about them for now, but the Approve task should be configured.
3. To configure the Approve task, go over the task and click on the icon . A Node properties window pops up and is divided into five tabs:

• General: Configure the main properties of the task like assignees, title, directive...
• Variables: Define local variables for this node.
• Form: Will be displayed to the user and enables interaction with her/him. Buttons are also configured here.
• Transitions: Define here all the possible ways to go out of the node and the conditions to follow one transition or another.
• Escalation Rules: Set up rules to be triggered if your task sleeps for too long for instance.

Approve Task General Tab

1. Go to the General tab.
2. Choose a title for the task: "Technical Doc Validation".
3. Choose a directive that will be displayed in the workflow dashboard: "As you are responsible for this nature of document, you are responsible for the document validation."
4. Remove the Due date expression as we will not use it. But that would be very useful to define an escalation rule for instance.
5. In Assignees, you can define static assignees (users or groups) for the task; click on Add and type Administrator.
6. In Compute additional assignees, you can make some computations to automatically designate the assignees. That will be useful later, but for now, empty the field.
7. You have access to others options (like Mail Notification, Allow task reassignment) but we'll leave them empty for now.
   ×
   

Approve Task Variables Tab

In the Variables tab, you can remove Assignees as we do not need it. We may need to add some other variables at some point, but we do not need it for now.

Approve Task Form Tab

The Form tab enables to choose how to interact with the user. You can drag and drop fields here if variables are defined for the workflow or node.

We just want the user to approve the task for now so nothing is required in the form. But we can change the label of the button at the end of the page and type "Accept the document".

Approve Task Transitions Tab

1. In the Transitions tab you will see that there is already the transition we need, so do not change anything. You can notice that the condition for the Approve condition is NodeVariables["button"] =="approve". This is because when a user clicks on a button, it puts the name of the button in a node variable called Button, so by using its value, the workflow engine can know what button was clicked on and compute what transition to follow. You can set more complex condition based transitions on other workflow variables for instance.
2. We do not want escalation rules for now, so you can leave the corresponding tab for now.
3. Click on the Save button of the Node properties popup, and click on the Save button of the workflow.

You now have a very simple workflow enabled on DocumentationItems that follows a simple path. You can deploy your Studio on your server and test you workflow. It should create a task for Administrator and do nothing after validating the task. The next step is to automatically compute the Assignee depending on the nature of the document.

Computing Assignees Dynamically

If you followed the first part of the tutorial (Documentation Item Implementation), you have a DocumentationItem that can have three possible natures. We want to have a different user responsible for each possible nature:

• Procedure (proc) -> Bill
• Notice (not) -> Julie
• Installation Instruction (inst) -> Steve

Of course, the responsible can change over time so you do not want to hardcode the value in the workflow but make it possible for an administrator to change the mapping without restarting the system just for that. The use of a vocabulary to store both the nature key and its mapped responsible seems like a good solution. We will compute the Assignee of the task from this vocabulary and the value of the Nature stored on the DocumentationItem.

1. First create a Vocabulary called natMapping and populate it with the values explained above: a nature (the key not the label) and a user name (we will create them later).

   You should get a vocabulary like this.

   ×
   
   How to create a Vocabulary

   We already created a Vocabulary in a previous tutorial of this series. If you do not remember or did not follow the tutorial, you will find the information at the end of the page Documentation Item Implementation. For each key of the natQual vocabulary, you should have the same key in natMapping with the corresponding responsible user name as a label.

   You can also refer to the page How to Add a New Vocabulary.

2. Go back to the workflow graph, on the Approve task of the workflow and edit it.
3. In the Assignees field, remove the Administrator by clicking on the icon .

4. Edit the field Compute additional assignees by clicking on the icon on the right.

   ×
   
   A window pops up in which you see a drop down list called Browse Context, in this list you have access to many variables you can use to compute information.
   Browse context

   The langage used here is called MVEL. For more information on to use MVEL in Nuxeo, you can browse to the page Use of MVEL in Automation Chains.

   What is interesting for us is that in the Context, we have access to a list of functions and one of them is Fn.getVocabularyLabel(String vocabularyName, String key) which gets a value from the named vocabulary that is associated with the given key. This is exactly what we want to do here: we want to get the user name (the vocabulary label) in the vocabulary natMapping created before for the nature (our key here) associated to the document. So will replace vocabularyName by our natMapping vocabulary and replace the key parameter by an expression that get the nature of the attached document.

5. In the Browse context drop drown list, select Fn and then getVocabularyLabel("voc","key") and click on Insert.
6. Replace "voc" by your vocabulary name: "natMapping" (you should keep the quotes as it is a String that is expected).

7. Remove "key" and leave the cursor here.

8. In Browse Context, select Document and then ["xpath"] and click Insert.

   This the way to access a document property.

9. You should replace "xpath" by your actual metadata which is "dc:nature".

   Your final expression should be: @{Fn.getVocabularyLabel("natMapping", Document["dc:nature"])}.

   xpath

   In many places in the Nuxeo Platform, you will be asked for a XPath which is a way to reference a metadata. A metadata in the Nuxeo Platform is always part of a schema, so to identify a metadata you only need the prefix of the schema (dc as dublincore for instance) and the name of the metadata, separated by a colon. Hence, the XPath for the nature of the document which is held by the schema Dublin Core is dc:nature.

   XPath are also used NXQL (Nuxeo query language). You will find other examples of XPath in the NXQL page.

10. Click on OK, save the node properties, save the workflow and redeploy your Studio project to your server.
11. On your server, as an Administrator, go to the Admin Center > Users and Groups, and create the three following users: Steve, Julie and Bill. Make sure you spell them exactly like you did in natMapping vocabulary.
12. Go to a DocumentationItem that has a nature and launch the workflow, it should be automatically assigned to the correct user.

We now have a workflow that self assigns to the right user but it still does nothing in the end: our document is still not validated. This is the next step.

Triggering Validation Logic with the Workflow

We have seen in Document Locking Right after Its Creation that business logic in the Nuxeo Platform is created with Automation Chains that are then triggered through different means (event handlers, user actions, APIs...). The exact same logic applies to workflows. Automation Chains can be triggered at different moment of the workflow :

• When entering a node,
• When exiting a node,
• On a specific transition.

So the general logic is so define when the chain should be triggered and then create the corresponding Automation chain.

As our workflow is very simple (only one button), we can put the validation logic almost anywhere: as an output of the validation task, as an input of Stop node or on the outgoing transition of the validation task. However, if we try to see a little bit further, we can probably choose wisely.

• We will probably add a Reject button to the task, so we do not want to launch the validation chain whenever exiting the validation task.
• The Stop node may be shared with other tasks in the future, so probably not a good choice neither.
• What we want is that the validation logic is triggered when the user clicks on a button Accept the document which will trigger the transition approve.

So in the end, let's bind our validation logic to the approve transition.

1. In Studio, edit the Approve task and go to the Transitions tab.
2. In the transition list, you will see on the left that you can either select an existing chain, or create a new one. Click on Create.
   ×
   
3. Choose a name so that will know this is the validation chain of the validation workflow, something like ValWf_ValidateDoc. You are redirected to the Automation Chain Screen where you can select the operation you need. In our case, we would like the document to be in a valid state. We have an operation that is called "Document > Follow Transition" that enables to change the state of the document depending of its life cycle. However, we did not set a specific life cycle for our document yet. So we should start with that.
4. Save your empty chain.

Setting the Life Cycle

1. Go to Document Model > Life Cycles.
2. Create a new one called technicalDocLifeCycle.
   ×
   

3. A life cycle needs an Initial State. Create one by clicking on Initial State and then clicking somewhere in the graph.

4. Go over the state and edit the state to name it draft.

5. Create two other normal states and call them valid and obsolete (we may not need this one for now).
6. Go over each state and link them to the others as shown on the following screen shot (you can move transitions by clicking on the dot on the middle).
   ×
   
   The transition are named automatically by Studio using the following pattern: to_state.
7. Save the life cycle.
8. Go to the DocumentationItem document type, and select the newly created life cycle.
   ×
   

Defining the Automation Chain

1. Now that the life cycle is defined, go back to the Automation chain ValWf_ValidateDoc.
2. Add the operation Documents > Follow Life Cycle transition. The expected parameter is the name of the life cycle transition you want the document to follow: to_valid in our case.
3. Add the operation Document > Snapshot version with the parameters:
   • Increment: Major
   • saveDocument: checked. It will create a new version of the document each time it is validated.In the end you should have:
     ×
     
4. Save the chain, deploy your project, create a new DocumentationItem with a nature metadata and enjoy your workflow.

The next step is to add some steps to the workflow so that the validator can ask for more information.