Tasks make collaboration better. Tasks are better than messages because they have a clear status and an assignee. Users can go to the Pulse to see who owns a task and perform actions on it. Magnolia uses tasks in the publishing workflow. When an editor publishes a page, the system creates an approval task and sends it to the publishers group. Under the hood we use the jBPM workflow engine's user task feature. See also Custom tasks and User tasks in Magnolia workflow documentation.
A task is an object that you create using the TasksManager . You can send the task to a list of users or to a list of groups. The recipient can assign the task to himself. Other recipients can see who owns the task and its status when they go to the Pulse.
When working with tasks, use the
TasksManager class which takes care of updating fields such as
status and notifies the system event bus.
TasksManager in your implementations, use injection:
Creating a task
Start by giving the Task a name. The name is unique for the type of task you are creating and acts as a reference to the task definition in the registry.
Next, define the possible assignees for the task. You can send a task to a list of
content to your task. The
content should contain the information the assignee needs to complete the task. For example, in the default publishing workflow the
content contains information the publisher needs to review a page and publish it such as the workspace where the page resides, a path to the page node, and the version of the page being published.
content map is stored to JCR using OCM and allows storing any
<String, Object> map where
Object is a simple type. The data inside the content map is usually only used for displaying information in the Pulse.
Claiming a task
When a user assigns a task to themselves they claim it. To claim a task, set the
This will update the task
modificationDate and notifies the system event bus.
info.magnolia.ui.admincentral.shellapp.pulse.task.action.ClaimTaskAction inside the Pulse for this step.
Resolving a task
To resolve a task assigned to an actor:
A resolved task usually produces some sort of output. You can use the
result map to pass this output to further processing.
TasksManager will take care of notifying any handlers registered to the system event bus.
info.magnolia.ui.admincentral.shellapp.pulse.task.action.ResolveTaskAction inside Pulse for this step. It allows you to define a decision inside the configuration which is mainly used for approving or rejecting a publication.
After resolving the task using the
ResolveTask action the result map contains only one entry with the configured decision.
As with the
content map, the
result map is stored to JCR using OCM and allows storing any
<String, Object> map where
Object is a simple type.
Archiving and removing a task
TasksManager provides a method for archiving tasks. The method removes the task from Pulse. You can still retrieve an archived task later in case you want to re-open it or audit.
While the API allows deleting a task, we strongly discourage doing so unless you know for sure that the deleted task won't be used any more.
Every task is bound to a life cycle and transitions back and forth between statuses as it proceeds in your process:
Created: The Task has been created but is not assigned to any actor.
InProgress: The task has been assigned to a user
Resolved: The task has been resolved by the assigned actor.
Failed: The execution of the task has failed.
Archived: The task has been removed from the Pulse.
Removed: The task has been removed from the repository. Removing tasks is supported by the API but should be used carefully. Depending on the use case, a user should be able to re-open a task after it has been resolved.
Changes to task status can be tracked by registering a TaskEventHandler to the system event bus.
Every task type needs a unique name. The name is used to read the task definition from the task registry in your module configuration.
The simplest TaskDefinition needs the following properties:
name: The node's name used to look up the configuration for a task.
title: The i18nable title of the task displayed in the tasks list in The Pulse.
taskView: The view definition used to render the form and action bar in the detail view of The Pulse. This is a reference to a
class: The class mapping used for node2bean to initialize the POJO.
As with any definition used in Magnolia, you can define your own extensions to the task definition and add configurable nodes and properties. This is especially useful in combination with a custom task presenter for putting together the detail view.
While we use the term task view for the detail view of a task, it is technically a message view used to render the form and action bar.
Use a message view configuration to define which fields of the task object are displayed to the user. You can use a dot notation such as
content.groceries to reference fields from the
result map. In the same fashion, you can configure your actions, including availability and action bar mappings.
A task presenter is started when a user opens a task to see its details. The presenter builds the form and action bar which are displayed to the user in the browser. Magnolia provides a DefaultTaskDetailPresenter . See Task view above for its functionality.
Most likely the task data you want to display in the Pulse can be rendered with the
DefaultTaskDetailPresenter. But in case the default presenter is not sufficient you can implement your own presenter and have it render whatever view is needed.
To implement a custom presenter, extend or use
and add a
presenterClass property with a custom implementation of the
interface to the configuration.
In your implementation, you can access the task object as well as its definition using injection: