A typical use case of content routing is that a user creates a route by giving it a name and a description. Then he can add steps or groups of steps (step folders). A step is associated with a chain of operations. A step folder is a container that can be either serial (each step runs one after the other) or parallel (all steps in it are run at the same time).
Routes, steps and steps folders are persisted in Nuxeo using documents. In this section, we will see how to create steps:
Step document type creation
What steps to create?
When creating an application using routing, the first question to answer is: what kind of step should a user be able to create ? In other words, what actions can be run through the route. For the following section, we will take an example to illustrate the configuration necessary. Here, we allow users to choose from three different types of steps:
- A step that assigns a task to a user: the user will be able to validate or refuse the set of documents attached to the route.
- A step to publish the documents: this step will publish the set of documents to a section chosen by the user in a remote Nuxeo instance.
- A step that sends a mail with all documents in the route attached.
From this example, we note two important things:
- The first step creates a task for a user. However, the content routing module is not a task management module. A task manager is not provided as part of the module. It is the responsibility of the user of the module to create tasks where necessary.
- When a step is run, it can either return as completed or open. A publishing step would return as completed automatically as there is no user interaction. A task step would remain open until the task is completed. This creates a waiting state when the route is running, where we wait for outside input (user input).
How to create a step?
Once we know what steps we want, the next questions to answer are: what part of the step should be configured by the user running/creating the route? What part of the step should be configured by the admin running the server ? Of course, this depends entirely on your use case and steps.
For our example, we choose:
We will create a document type for each type of step and add a schema with fields for each user configurable data. The type needs to extend the
Creating the document type
We create three document types with their own schema to add their specific metadata. The three new types extend the
DocumentRouteStep document type. The
DocumentRouteStep type is a very simple step that becomes done as soon as it is run.
You can look at Nuxeo EP documentation on how to create schema and document type. You can also have a look at the routing components and CMF components: the creation of step type in CMF shows the definition of 4 types of steps:
They're all related and so use the same schema to persist their metadata.
Adding the layout
We add layouts to each type of step. As for any Nuxeo document type, we add Create, Edit and View layouts. When creating the layout, we should keep in mind that the person creating the steps and the person editing the steps often have very different functional roles. The Layout contribution for CMF shows an example of layout.
Adding actions to a step
Creating an automation chain
In the previous section we saw how to create a type of
DocumentRouteStep to be able to persist data specific to our step. In this section we will see how to run a step. What we want to do depends on the step:
- For the task step, we want to get the assignee name, the due date and create a validation task for the assignee on the attached document.
- For the publication step, we want to get the path of the section and connect to the remote Nuxeo application to publish the attached documents.
- For the mail step, we will get the message, the mail address, create a mail, attach the documents to it and send the mail.
For each of these steps, we will create an automation chain that will do the work. This automation chain will be provided, in its context, with the document attached to the route and the step document that is running. So, for example, the mail step automation chain will do:
- get the address and message from the step document
- get the attached document from the context
- send the mail with the value collected
The Content Automation section will show you how to create operations and operation chains. You need to read it first if you plan to create operation manually. You can also use Nuxeo Studio.The routing module adds to the context the step document with key
document.routing.step. It allows any operation run to access the
DocumentRouteStep and then the route and the attached document. This the duty of the automation chain to notify the route if the step is done or not (in other word if we are in a waiting state or not). We provide the
setDone method on the step to do it. We also provide ResumeStepOperation you can use in you chain. Its only function is to call the
setDone method on the step attached to the chain.
Binding automation chain and Step document type
Once you created your automation chain to run the step, you finally bind together the document type for the step you created and the corresponding automation chain. This is done using the
For each step document type, you need to contribute the operation chain that is called when the step is run. You also need to contribute an operation chain that will undo the step when it has already been done, and a third one that will undo the step when it is running.