Route processing and lifecycle

We have seen in the previous section how to create steps and define what will be done when the step is run. In this section we will see how a user creates a route and runs it.

Basically, when users create a route, they actually create a model of route, that will need to be validated in order to be used on documents. What is run on the documents is actually an instance of the route, that can be canceled. All these steps of the route evolution are explained below.

Creating a route

Where can I create a route?

A route is a document, called DocumentRoute. Via the user interface, the user will click on the on the "New" button. He will be able to select the DocumentRoute document type. He chooses if the route is serial or parallel. Default value is serial. He can then add folder (choosing again if they are serial or parallel) and steps. All the contributed step types are available to choose from. When creating the step document, he fills in the value using the layout contributed in the previous section.

In the default Nuxeo CMF implementation, this is the type service that decides where a user can create some types of document. The default routing configuration allows anyone to create a route inside a workspace or a folder. As users can only access workspaces and folders from their personal workspace in CMF, it is actually the only place where users can create routes.

When the user is done, he gets a hierarchy of Route elements like this workflow for instance:

In this example workflow, the route is composed of steps that can be grouped in parallel step folders (in grey) or serial step folders (in blue). This route is currently a model of route that users will be able to use on their documents. All route elements are at the "draft" state.

How can I validate the route?

The route we created is a model of route. This means that we didn't attach any document to it for processing. Before the route is made available to users so they can run it with attached documents, it needs to be validated. To validate the route, we call the method validateRouteModel on the DocumentRoutingService.

The default UI makes the "validate model" button only available to user who belongs to the routeManagers group. You need to create this group and add users to it. In the CMF, if you are not a route manager, you need to:

1. Go to to your personal space (this is the only place in CMF where a user can create non Case/CaseItem types of document).
2. Create the route.
3. Add to the permission read/write to a routeManagers on the route or one of its parent folder.
4. Inform route managers that the route needs validation.

Once a route is validated, it is immutable and all the elements of the route are at the 'validated' state. It also becomes readable by everyone.

What routes are available?

The method getAvailableRouteModel on the DocumentRoutingService returns a list of route models. This is a simple query done with the session of the user. If you need to make only some routes available to some users, you can override the query DOC_ROUTING_SEARCH_ALL_ROUTE_MODELS in the query model contribution. This query will return the list of route names in UI suggestion box for route.

Running a route

What does it mean to start a route?

When a user wants a set of documents to go through all the steps of a route, he starts the route on the document. In the UI, he can do it either from:

• the "Summary" tab of a document, selecting a route from the ones available and starting it;
• from the "Summary" tab of the route, selecting the document and starting the route.

From the Summary tab of the route, the suggestion widget offers documents found with the CURRENT_DOC_ROUTING_SEARCH_ATTACHED_DOC query model, that can be found in the query model contribution. This contribution can be overridden to fine graine the documents on which users can start a route.

What happens when we start a route on a set of documents?

When we start a route on a set of documents, the route model that we chose stays completely unmodified. The route that the user created and validated is unchanged. When we start a route:

1. A copy of the route hierarchy is created in a hidden folder at the root. We will call this copy an instance of the route.
   Administrators have access to this hierarchy: this is useful for debugging and finding problems.
2. The IDs of the attached documents are set on the route instance.
3. All the elements of the route are set to the ready state.

So it is actually the instance of the route that is run, and that can be modified. An instance always has attached documents. Modifications on the instance only affect this instance. A user might change an instance of a route by adding/editing/deleting steps. The method saveRouteAsNewModel in the DocumentRoutingService will enable users to save the modified instance in a new route model. It will copy the instance route in the user personal workspace, in the "draft" state only changing its name (adding (COPY) to its name).

The set of methods createNewInstance in the DocumentRoutingService allows to create an instance of a route with attached documents and start this instance.

Running the route

When a route starts, it calls the method run on each of its children (folder or steps). All elements do:

1. set itself to 'running',
2. run,
3. set itself to 'done' if needed.

The 'run' actions depend on the element it is applied to:

• steps will call the automation chains bound to the type of the step,
• folders will call the run method on their children and set themselves to done if their children are done.

We see that the lifecycle states of the elements of the route tell us how advanced we are in the processing of the route. The lifecycle is the same for all the elements (route, folder and step):

• to Validated: The document route is being validated. All the elements of the route become validated at the same time.
• to Ready: A new instance of the route is created in the DocumentRouteInstances folder. All the elements of this new route instance are at the ready state.
• to Running: The element is being run. Each element of the route reaches this state one after the other. The step is at the running state when the operation chain bound to it is being run.
• to Done: The element is done.
• to Canceled: When a route is canceled, all its element are canceled. The undoFromRunning and undoFromDone operation chain are run depending of the state of the canceled element.

For each transition taken, there is an event sent that you can use to plug some functionalities. Note the stepWaiting event, that is sent when the step runs the operation chain and returns still at the 'running' state. This means that the step is waiting for an outside event to resume. In this case, this is the responsibility of the outside event to resume the route.

Note about lifecycle transition

The BulkLifeCycleChangeListener in Nuxeo is a listener that recurses lifecycle change from a folder to its children. This is especially useful when deleting a document: when a folder is deleted (ie: lifecycle goes to deleted), we want all of its children to be deleted.

However, this is problematic for DocumentRoute documents as we don't want, when a route is set to 'Running', that all of its children are set to 'Running'. This is also problematic because the children is a post commit listener. This means that when the first step of a route goes from 'Validated' to 'Ready' to 'Running' in one go, it will complain that it is in 'Validated' state if we rely on the post commit listener to take the transition. To avoid this problem, this transition uses the non recursive attribute in their declaration.

RELATED TOPICS
Events and listeners
Nuxeo EP platform overview
Content Routing documents