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.

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...
• Activation: 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.

Activation Tab

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

1. Go to the Activation 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.

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 an Approve task from the left (Start and Stop nodes are already there).
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: Main properties of the task like assignees, title, directive...
• Variables: Local variables for this node.
• Form: Will be displayed to the user and enables interaction with her/him.
• Resolution Actions: To configure buttons on the task for the users.
• Transitions: To define all the possible ways to go out of the node and the conditions to follow one transition or another.
• Escalation Rules: To 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 Assignees expression, 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.

Approve Task Resolution Actions Tab

Just one Approve button is enough for now but we can change the label of the button 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.

Computing Assignees Dynamically

If you followed the first part of the tutorial (Implementing Documentation Items), 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 Implementing Documentation Items. 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.

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 "qa:nature".

   Your final expression should be: @{Fn.getVocabularyLabel("natMapping", Document["qa: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 qa: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 lifecycle. However, we did not set a specific lifecycle for our document yet. So we should start with that.
4. Save your empty chain.

Setting the Lifecycle

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

3. A lifecycle 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 lifecycle.
8. Go to the DocumentationItem document type, and select the newly created lifecycle.
   ×
   

Defining the Automation Chain

1. Now that the lifecycle is defined, go back to the Automation chain ValWf_ValidateDoc.
2. Add the operation Documents > Document.FollowLifeCycleTransition. The expected parameter is the name of the lifecycle transition you want the document to follow: to_valid in our case.
3. Add the operation Document > Document.CreateVersion 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.