Getting Started

Simple Workflow Example

Use Case

A company has decided to be more rigorous on proposals sent by the sales team. A workflow has to be set up so that each proposal is reviewed by the head of operations, this one being able to decide of an additional juridical control.

The graph we want is like this:

Prerequisites

The following operations have to be done in your Nuxeo Platform before following this tutorial:

  • Create a user having for id Emily, a sales employee who launches the workflow, and give her ReadWrite access on the domain.
  • Create a user having for id Jack, as Head of Operations, and give him ReadWrite access on the domain.
  • Create a group having for id Internal_Lawyers and populate it with at least one user (like Internal_Lawyers1).

You can perform these operations from the Web UI Administration menu and the domain permission tab. For advanced users, you can alternatively use the Users and Groups menu in Studio Modeler and update the Domain Structure Template (DomainFactory) to grant the required permissions.

Implementation Steps

Creating the Workflow

  1. In Studio Modeler, navigate to the Workflow > Process Definitions submenu.
  2. Click on the New button.
  3. Give the workflow an id (SalesProposalWorkflow), a label and a description.
    simple_Workflow_000.png
    simple_Workflow_000.png
  4. Click on the Ok button.

Defining the Workflow's Activation

Workflows can be launched through a dropdown list on the summary screen of every document. Into the Activation tab, you can decide for which type of document the workflow you do will be usable, for which group of users, etc.

  1. From the workflow, click on the Activation tab.
  2. In the Current document has one of the types, select File.
    simple_Workflow_002.png
    simple_Workflow_002.png

Starting the Graph

A workflow must start with a node for which the "start node" property is checked and have at least one end node with the "end node" property checked.

To start the workflow graph:

  1. Click on the Graph tab.
  2. By default, Studio adds the Start and Stop nodes automatically. If not, drag and drop the Start node on the graph.

Defining the Technical Validation Step

Let's create and configure the technical validation step.

This node will create a task for Jack, the head of operations. He will have to accept or reject the proposal submitted by the salesman or decide that it requires a juridical advice.

Drag the Accept/Reject node template from the node template library and drop it on the graph. It will already have some of the needed transitions and buttons pre-configured: Validate and Reject. You need another transition (Need juridical advice), which you will add manually in a future step.

simple_Workflow_003.png
simple_Workflow_003.png

  1. Hover on the Accept/Reject node you just dropped and click on the icon that appears to open the node properties.
    simple_Workflow_005.png
    simple_Workflow_005.png
  2. In the General tab edit the following properties:
  • Title: Technical validation
  • Due date expression: CurrentDate.days(5)
  1. Update the assignee related fields:
  • Assignees: Add a statical assignee (Jack). Click on the "Add" link in front of the "Assignees" field.
  • Grant permission to task assignees: Leave this field blank.
  1. Click on the Save button of the popup.
  2. Click on the Save button of the workflow feature on the bottom left corner.

technical-validation-node.png
technical-validation-node.png

Configuring the Workflow Variables

During this task, we want to capture the head of operations' comment. We could use a node variable, but using a workflow variable is more appropriate as it will let us leverage the head of operations' comment value in the other nodes. For example, to display it to the other users in their own task validation form, to know what was the option of the head of operations when taking the decision. Getting the juridical advisor and salesman's comment are needed at a later stage, so that workflow variables are added to their comments as well.

This variable will be named hoo_comment.

To add the workflow variables:

  1. Click on the Variables tab of the workflow.
  2. Add the head of operation's comment variable and name it hoo_comment. It is like editing a schema.
  3. Add the juridical advisor's comment variable: juridical_comment.
  4. Add the salesman's comment variable: sales_comment.
    simple_Workflow_004.png
    simple_Workflow_004.png
  5. Click on Save.

Configuring the Technical Validation Step Layout and Actions

Initializing the Task Layout

The workflow task layout lets the user edit some of the workflow's variables (either at workflow level or node level), and the buttons help the engine to know which transition to play after the node, depending on what the user clicked on.

  1. Go back to the Technical validation node.
  2. Click on the Variables tab. Add the hoo_comment to the right column.
    technical-validation-layout1.png
    technical-validation-layout1.png
  3. Save your work.
  4. Click on the Configure layouts in Designer button.
    technical-validation-layout2.png
    technical-validation-layout2.png
  5. Select the Technical validation task and click on the Configure button.
    technical-validation-layout3.png
    technical-validation-layout3.png
  6. Delete the properties already displayed in the layout using the delete icon once an element is selected. Keep only the "hoo_comment" property.
  7. Change its label for Head of Operations Comment.

Setting up the Tasks Buttons

In Studio Modeler, the buttons that are shown on the form are configured on the Task Buttons tab. Two are already available because of the template node you chose. You need to add a third one when the document requires juridical expertise.

  1. Go back to the graph of the workflow on Modeler side.
  2. Click on Add task button.
  3. Fill in the button id require_juridical_advice and label Require Juridical Advice?.
  4. Let the box Generate the condition for the transition checked.
    Simple_Workflow_008_1.png
    Simple_Workflow_008_1.png

Check the Transitions

Each button is automatically associated to a transition to define what should be done when the user clicks on the button. Transitions automatically get a condition, which is a system node variable called "button". This variable is systematically updated with the id of the button used to process the task. It is useful to configure the behavior of the transitions.

  1. Finally, click on the Transition tab. Note that you could add more terms in the condition if necessary.
    technical-validation-transitions.png
    technical-validation-transitions.png
  2. Click on Save.

Connecting the Nodes

  1. Go back to the graph.
  2. Link the Start node to the Technical validation node, by pulling an arrow between the unique transition point of the Start node to the input point of the Technical validation node.

    simple_Workflow_012.png
    simple_Workflow_012.png

    Note that you have three transition points on the technical validation node, ready to be pulled to the next nodes.

Defining the Juridical Advice Node

Now that we have our Technical validation node set up, we need to create the nodes used for its possible transitions. First comes the Juridical advice node. As most operations have been described before, we will only comment this node’s specificities.

Configuring the Node

Drag the Approve node from the node template library and drop it on the graph.

  1. Open the node properties.
  2. Rename the node to Juridical advice.
  3. Define the assignees.
    This time we would like to ask a member of the “Internal_ Lawyers” user group to comment instead of a specific person. Therefore, instead of adding a specific username, you may simply add an assignee and use the prefix group: to specify a user group (group:Internal_Lawyers).

  4. Grant the appropriate rights. The internal lawyers may not have the necessary rights to read and/or edit a sales proposal document. To avoid an exception to be thrown because of this, you need to grant them the appropriate rights on the document that needs juridical advice temporarily. This is what the Grant permission to task assignees field is used for. In this case, choose the Read & Edit permission to let them modify the document. Keep in mind that these rights will only be granted during the operations made on this node, and reverted to their previous state when following a transition to another node.

    juridical-advice-node.png
    juridical-advice-node.png

Configuring the Task Layout

  1. Click on the Variables tab and add the juridical_comment and hoo_comment variables to the right column.
    juridical-advice-node2.png
    juridical-advice-node2.png
  2. Save you work
  3. Click on the Configure layouts in Designer button.
  4. Open the Juridical Advice workflow task and click on the Configure button.
  5. Delete the properties displayed in the layout using the delete icon once an element is selected. Keep only the hoo_comment and the juridical_comment properties.
  6. Select the juridical_comment field and set the property as required.
    vd_wf_technical_validation_layout6.png
    vd_wf_technical_validation_layout6.png
  7. Select the hoo_comment as well, change its label for Head of Operations Comment and set the property as read only.
    juridical-advice-layout.png
    juridical-advice-layout.png
  8. Click on Save.

Connecting the Nodes

  1. Go back on the graph, in Studio Modeler.
  2. Search for the Technical validation node’s juridical advice requirement output point.
  3. Pull an arrow from there to the Juridical advice node’s input point.
    simple_Workflow_018.png
    simple_Workflow_018.png

Defining the Proposal Update Node

You will now take care of the Proposal update node, which will be used in case Jack refuses the proposal.

Adding the Node

The Approve node will once again be the most appropriate. Pick it up and drop it on the graph.

Configuring the Proposal Update Node

  1. Open the node properties.
  2. Rename the node to Proposal update.
  3. Rename the directive: Proposal update.
  4. Define the Due date expression: CurrentDate.days(5)
  5. Define the assignees.
    This task may not be assigned to a particular person, neither may it be assigned to a group. It needs to be assigned to the document's creator. To do so, a variable needs to be used instead of a hard coded value. We use the Assignees expression field and use this variable: @{Document["dc:creator"]}. This will return the document creator's username. Note that there are no specific rights to grant there as in this situation the document will be heading back to its creator.
    proposal-update-general.png
    proposal-update-general.png
  6. Calling the task an approval task could lead to confusion for the salesman that wants to submit an updated proposal. Thus, we will call the task button differently:
    1. Click on the Task Buttons tab.
    2. Delete the approve existing task button.
    3. Click on the Add task button link.
    • id: submit_updated_proposal
    • Label: Submit updated proposal
      simple_Workflow_022_1.png
      simple_Workflow_022_1.png
  7. Save.

In this scenario, if Jack (Head of Operations) rejects the tasks, it is sent back to the document creator. We could have used the workflowInitiator expression so that the task is returned to the user who has launched the workflow (assuming it could have been distinct from the document creator).

Configuring the Task layout

  1. Click on the Variables tab and add the sales_comment and hoo_comment variables to the right column.
    proposal-update-node.png
    proposal-update-node.png
  2. Save you work.
  3. Click on the Configure layouts in Designer button.
  4. Click on the Configure button next to the Proposal Update layout.
  5. Delete the properties displayed in the layout using the delete icon once an element is selected. Keep only the Hoo Comment and the Sales Comment properties.
  6. Change the hoo_comment label for Head of Operations Comment and set it as read only mode.
    proposal-update-layout.png
    proposal-update-layout.png

Removing the Approve Transition

  1. Go back to the Proposal update node, in Studio Modeler.
  2. Click on the Transitions tab.
  3. Click on the icon next to the "approve" transition and click on Remove in the contextual menu.
    proposal-update-transitions.png
    proposal-update-transitions.png
  4. Confirm row deletion on the popup window.
  5. Click on Save.

Connecting the Nodes

  1. Go back to the graph.
  2. Link the reject output of the Technical validation node to the Proposal Update node's input.
  3. Link the Proposal update node's output point to the Technical validation node's input point.
    simple_Workflow_024.png
    simple_Workflow_024.png
  4. Link the validate outpoint point of the Technical validation task to the end node.
  5. Link the approve outpoint point of the Juridical advice task to the end node as well.

This node sets a possible ending to the workflow. In this situation only one end node will be used, but remember that you may use several end nodes if needed.

Automating Document's Metadata Update

A document being accepted by the Head of Operations or the Juridical services has to see its metadata updated. This is something we can achieve through an automation chain.

  1. Open the Stop node properties.
  2. In the General tab, click on the Create button next to the field "Select the input automation chain".

    empty-end-node.png
    empty-end-node.png

    1. Give an id to your chain: SetAsApproved.
      simple_Workflow_026.png
      simple_Workflow_026.png
    2. In the editor, add the Document > Follow Life Cycle Transition operation using drag and drop.
      empty-automation-chain.png
      empty-automation-chain.png
    3. Open it and set its value to approve.
      simple_Workflow_028_1.png
      simple_Workflow_028_1.png
    4. Save the chain and go back to your workflow graph.
  3. Now that the chain is created, you may have a look at your end node properties. The input operation chain has been automatically filled in thanks to our previous operation.

    end-node-setasapproved.png
    end-node-setasapproved.png

Deploy and Test

  1. Log in as Administrator.
  2. Hot reload your instance to deploy the Nuxeo Studio Configuration.
  3. Navigate to Domain > Workspaces and create a Proposals workspace.
  4. Create a file in the Proposals folder.
  5. Log out and log in as Emily and open the proposal you've just created.
  6. Click on the Start Process button.
    simple-worfklow-step1.png
    simple-worfklow-step1.png
  7. Select the Sales Proposal workflow.
    simple-worfklow-step2.png
    simple-worfklow-step2.png
    You should see a information banner indicating a workflow as been triggered. As a workflow initiator, you can View the Workflow graph or Abandon it.
  8. Log in as Jack: there's a new task in your dashboard as well as a notification on the workflow task menu.
    simple-worfklow-step3.png
    simple-worfklow-step3.png
  9. Open the task, add a comment and send it for review to the Internal Lawyers by clicking on the Require Juridical Advice button.
  10. Log in as one member of the Internal_Lawyers group: there's a Juridical Advice workflow task.
    Il you click on the document, or try to navigate, you won't be able to see the Domain > Workspaces > Proposals folder structure as we have just given Read and Write access to the document for this group.
  11. Add a comment and approve the document.
    simple-worfklow-step4.png
    simple-worfklow-step4.png
    Once completed, the task performer of the "Require Juridical Advice" task can no longer access the document.
  12. Log in as Jack and open the document: the document status has been updated to Approved.
    simple-worfklow-step5.png
    simple-worfklow-step5.png

You can execute again the workflow with another document and pass through the Reject task.

We'd love to hear your thoughts!

All fields required