Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

Magnolia ships with a basic "four-eye" editorial content workflow. Authors and editors come across this pre-defined workflow for the first time when they activate content. Activations are submitted to a workflow queue for approval. A publisher can examine the workflow item, see what the changes are, who made them and when, and decide whether to publish the modified content to a public instance.

The key point about the default workflow is that authoring and editorial review happen on the author instance. Content is published to public instance only when the workflow is completed.

Engine

Magnolia uses the cross-platform OpenWFE workflow engine (manual). OpenWFE allows extensive workflow customization, making it possible to integrate Magnolia into your legacy business processes. You can define your own activation and publishing workflows with as many stages and participants as needed.

The engine supports:

  • Linear modeling and approvals.
  • Branching and merging.
  • Conditionals such as IF and multi-choice.
  • Auto-escalation.
  • Email notifications.
  • Pre-defined workflows.

Workflow definition

Workflows are defined in XML. You can use a third party editor with syntax highlighting to enhance the editing experience. Generally we assume that workflows are defined by suitably skilled people. OpenWFE provides a flexible set of rules to accommodate business requirements and the XML markup is clean. Example:

<process-definition name="activation" revision="j0.0.2">
   <sequence>
      <set field="activator" field-value="userName"/>
      <!-- Go to publisher first -->
      <to-publisher/>
      <!-- Will loop if rejected -->
      <if test="${field:action} == reject">
         <revision-round/>
      </if>
      <log message="activate: ${field:action}"/>
      <!-- If the last action was proceed then activate-->
      <if test="${field:action} == proceed">
         <activate/>
      </if>
   </sequence>

Workflow definitions are added and edited in AdminCentral in Configuration > Workflows. The system stores them in /modules/workflow/config/flows/.

Accessing dialog fields

Workflow definitions have access to the workflow dialog's fields. Timed activation of content is an example of this. When you launch a workflow you can indicate optional publication and expiration dates.

The dates are stored in the workitem in content nodes named after the startDate and endDate fields in the startActivationWorfklow dialog.

The activation workflow can read the dates using the ${f:<field name>} syntax and activate and deactivate content accordingly. The letter f stands for field. ${field:<field name>} works too.

<process-definition name="activate">
   <sequence>
   <!-- Wait if scheduled -->
   <if>
      <defined field-value="startDate"/>
      <sleep until="${f:startDate}"/>
   </if>
   <!-- Deactivate if scheduled -->
   <if>
      <defined field-value="endDate"/>
      <sequence>
         <sleep until="${f:endDate}"/>
         <participant ref="command-deactivate"/>
      </sequence>
   </if>

In addition to startDate and endDate, the following properties are available. comment is the only field displayed in the dialog, the rest are just properties passed to the workflow definition.

  • action performed by the user such as "activate", "proceed", "reject"...
  • activator. In the sample activation workflow we set activator value to the user who launched the workflow. If a publisher rejects the change, we assign the workitem back to the activator.
  • username of the current user who lauched the workflow.
  • repository or workspace where the activated content item resides such as website.
  • path to the activated content item such as /demo-project/about/history.
  • mailTemplate used for a workflow notification. Mail templates are configured in /modules/mail/config/templatesConfiguration.
  • mailto. Recipient(s) of email notification. This can be a group such as group-publishers. Group members whose email address is registered in their user profile will receive the notification.
  • comment entered into the Comment field in the activation dialog.

You can test these properties by writing their values to a log file.

1. Create a simple workflow definition named test. Log the property values using:

{{<log level="warn" engine-log="yes" message="<field name>: ${f:<field name>}"/>}} 

For example:

<process-definition name="test" revision="0.0.1">
  <sequence>
    <log level="warn" engine-log="yes" 
        message="Comment: ${f:comment}"/>
    <log level="warn" engine-log="yes" 
        message="Pub. date: ${f:startDate}"/>
    <log level="warn" engine-log="yes" 
        message="Exp. date: ${f:endDate}"/>
    <log level="warn" engine-log="yes" 
        message="Path: ${f:path}"/>
    <participant ref="group-publishers" />
  </sequence>
</process-definition>

2. Modify the activate command so it launches your test workflow instead of the default activation workflow. The workflow name is defined in /modules/adminInterface/commands/website/activate/startFlow/workflowName.

3. Activate some website content.

4. Observe the log file in apache-tomcat/logs/catalina.out:

WARN: Comment: Please review and publish.
WARN: Pub. date: 2010-09-01 00:00:00+0200
WARN: Exp. date: 2010-09-30 23:59:59+0200
WARN: Path: /demo-project/news-and-events

Creating your own fields

You can create your own dialog fields and read their value from the workitem the same way. This allows you to define custom fields such as "Legal review required" that routes a workitem to the legal department or "Publish immediately" that bypasses the review process.

Here's an example of a dropdown list (select control) with three options. The dropdown is defined in the startActivationWorkflow dialog in /modules/workflow/dialogs.

The dialog will display the new field when content is activated. Users can select who should review the content.

The workflow definition routes the workitem to the responsible group based on the selected field value.

<process-definition name="test" revision="0.0.1">
  <sequence>
    <case>
      <!-- Send to Marketing team -->
      <equals field-value="groupReview" 
        other-value="group-marketing"/>
      <participant ref="group-marketing"/>
      <!-- Send to Legal team -->
      <equals field-value="groupReview" 
        other-value="group-legal"/>
      <participant ref="group-legal"/>
      <!-- Send to Operations team -->
      <equals field-value="groupReview" 
        other-value="group-operations"/>
      <participant ref="group-operations"/>
    </case>
  </sequence>
</process-definition>

Participants

A participant is a reference to a user or program that takes part in the workflow. Participants are identified in the workflow definition by their name. OpenWFE understands four kinds of participants:

  • user-<user name>
  • group-<group name>
  • role-<role name>
  • command-<command name>

Users, groups and roles need to exist in Magnolia security before you assign a workitem to them. Example of assigning a workitem to user "john":

<participant ref="user-john" />

Workitems in inbox

Workflow tasks are called workitems. They arrive at a workflow participant's Magnolia inbox.

A participant acts on the workitem by completing the required task such as reviewing a page change.

Permissions to view workflow items are controlled through Magnolia user rights management. This allows an administrator or workflow supervisor to see workitems assigned to other users. Their inbox effectively functions as a "dashboard", displaying the status of the workflow process.

Since commands and processes can participate in a workflow, you can send email notifications on pending workitems. A workflow command can be attached to any event such as move page, activate, rename etc.

See Add custom column to inbox on how to customize the inbox.

Previewing a workitem in the inbox

The Show Content button displays a preview of the selected workitem. By default, you can preview items in the website and dms workspaces.

Example: Previewing a document in the dms workspace.

Custom preview functions

Workitem content preview works only in website and dms workspaces by default. To implement a preview for items in other workspaces, you need a custom function. Typically the custom function displays the edit dialog of the content item. You can implement the function in Java or in JavaScript.

Java class

Write a Java class that implements the  InboxShowFunction interface and provides a function. This is the more flexible option as you can execute any Java code before you return the function.

Configure the Java class in /modules/workflow/config/showFunctions.

Properties:

  • <workspace>: Name of the workspace for which the provided value function should be used, for example data. Set the value to a fully-qualified class name.

Here is an example class that displays the edit dialog for any data type in the data workspace. 

DataInboxShowFunction
public class DataInboxShowFunction implements InboxShowFunction {
    private static final Logger log = LoggerFactory.getLogger(DataInboxShowFunction.class);
    @Override
    public String getShowJsFunction(String path) {
        try {
            Session session = MgnlContext.getJCRSession("data");
            String dialog = session.getNode(path).getPrimaryNodeType().getName();
            if ("dataFolder".equals(dialog)) {
                // no preview for folders
                return InboxHelper.getShowJSFunction("data", path);
            }
            return "function() {" +
                    "mgnlOpenWindow(\".magnolia/dialogs/" + dialog + ".html?mgnlPath=\" + mgnl.workflow.Inbox.current.path + \"&amp;mgnlRepository=\" + mgnl.workflow.Inbox.current.repository + \"&amp;mgnlVersion=\" + mgnl.workflow.Inbox.current.version);" +
                    "}";
        } catch (RepositoryException e) {
            // the path doesn't exist anymore. This mean content in question was either deleted or renamed. Do not break inbox display because of it
            log.error(e.getLocalizedMessage());
            return "alert('The work item can not be displayed, because the content " + path + " can not be located.');";
        }

JavaScript function

Write a JavaScript function and inline it in the configuration.

Properties:

  • <workspace>: Name of the workspace for which the JavaScript function should be used, for example users. Set the value to an inlined JavaScript function.

Here is a function that opens the edit dialog for users in the users workspace.

function() {mgnlOpenWindow("/.magnolia/dialogs/useredit.html?mgnlPath=" + mgnl.workflow.Inbox.current.path + "&amp;mgnlRepository=users");}

Mail notifications

Magnolia can additionally, or alternatively, be configured to send workflow notifications by email using the Mail module. The workflow activation process definition is registered in /modules/workflow/config/flows/activation. The value contains the workflow definition.

A workflow definition is an XML file. It contains process definitions that adhere to the OpenWFE schema.

To edit a workflow definition, go to Tools > Workflow and open the activation workflow. If you scroll through the file you will see two process definitions relating to email notifications that are commented out.

<process-definition name="to-publisher">
  <sequence>
    <!--
    uncomment if you like to use an email notification
    -->
    <!--
    <set field="mailTo" value="group-publishers"/>
    <set field="mailTemplate" value="workflowNotification"/>
    <participant ref="command-sendMail"/>
    -->
    <!-- reset the assignTo field so the editor no longers see the workflow item --> 
    <unset field="assignTo"/>
    <participant ref="group-publishers"/>
  </sequence>
</process-definition>

To activate email notifications, uncomment the relevant sections and Save.

When an editor requests the activation of a page, document or data item, a notification is sent to users assigned to the publishers group. If the publisher rejects the activation request, a notification is sent back to the user who requested the activation. The activation process definition refers to two groups: publishers and editors. These groups were created by the Workflow module during installation and their members can be viewed in Security. For workflow email notifications to work correctly, valid email addresses are needed for users. For more information groups, users and roles, see Security.

The mail template workflowNotification is referenced in the workflow definition:

  <set field="mailTemplate" value="workflowNotification"/>
      <participant ref="command-sendMail"/>

The template is registered in modules/mail/config/templatesConfiguration:

And the template script file is inside the mail module JAR file:

<html>
  <head></head>
  <body>
    <h1>Magnolia Workflow Notification</h2. 
    <p>This mail has been sent by the Magnolia activation Workflow.</p>
  </body>
</html>

Secure activation of content to a public instance

For security reasons, having only one user account on public instances is preferable. From a system perspective, where workflow is in the place, the only account necessary in order to activate content is the superuser. See also Activation and Security defaults.

Integration with external processes

While typical workflow participants are users, also scripts and commands can participate. This opens up the possibility to execute jobs and launch external processes at a given workflow stage. Conversely, an external process can participate in a Magnolia workflow through a command or script.

Each module can provide its own commands. Commands are configured in /modules/<module name>/commands/<catalog name>/<command name>. A command is associated with a Java class through the class property.

For example, you could write a command that encapsulates the decision who (or which group or role) should receive the workitem next. The name of the "real participant" could be placed in a workitem field such as receiver.

<sequence>
    <participant 
    ref="command-determinereceiver" />
    <participant 
    field-ref="receiver" />
</sequence>

To reference a command that does not exist in the default catalog, include the catalog name: command-<catalog_name>-<command_name>, for example ref="command-contenttranslationsupport-exportContent".

  • No labels

2 Comments

  1. Hi!

    we are working on EE 4.5.19. I am logged in as a superuser. Superuser belongs to the group "publishers", thus should be able to see the workitems in the Inbox, right?

    Activation of website content works fine.

    Activation of dms content launches a workflow, but there is nothing in the Inbox, no workitems at all. When I look at the jcr tree of the "Expressions" workspace, I see nodes under /owfe/activation. Should those show up in the Inbox? And (of course) there is no activation done. Nothing shows up on public. And there is nothing in the log...

    Question: how can I make workitems visible in the inbox? (to approve them, so the activation is launched...!)

    Thanks!

    1. Hi Yann-

      For me to know exactly how and why this is happening we would need to investigate. So as an EE customer (or partner working on behalf of an EE customer) you can open a support request for that. For a quick fix, you should have a look here at Purging stuck activation and deactivation jobs. That really sounds like it could be the issue here. In newer versions of Magnolia we use jBPM rather than OpenWFE so we don't see this kind of issue arise anymore.

      HTH