Workflow integration

Search Engine Optimization auditors can be executed within a Magnolia workflow. You can use the results of executed auditors in a workflow.

This feature was added in v5.6.1.

ExecuteAuditHandler

ExecuteAuditHandle can execute selected auditors in a workflow and judge the audit results.

What auditors are executed depends on the configuration of ExecuteAuditHandler and the workflow context.

If the Magnolia workflow data (mgnlData) contains an item named "auditors," retrieves its value and treats it as a list of auditor names separated by commas to be executed in the workflow.

If an "auditors" item is not present in the Magnolia workflow data, ExecuteAuditHandler checks its definition for a list of auditors to execute. If the workflow item definition contains a list of auditors, they will be executed instead of the auditors configured in the work item handler.

ExecuteAuditHandler will report the results of the audit in the workflow context mgnlData. It adds a map called auditResults containing the following names and values:

Property Description

Property	Description
`status`	String, either `passed` or `failed`. The status depends on the settings of `failOnErrors`, `failOnWarnings` and `failOnNotes` for the `ExecuteAuditHandler` instance and the results of the audit.
`errors`	Integer, the number of errors found by the executed auditors.
`warnings`	Integer, the number of warnings found by the executed auditors.
`notes`	Integer, the number of notes found by the executed auditors.

status

String, either passed or failed.

The status depends on the settings of failOnErrors, failOnWarnings and failOnNotes for the ExecuteAuditHandler instance and the results of the audit.

errors

Integer, the number of errors found by the executed auditors.

warnings

Integer, the number of warnings found by the executed auditors.

notes

Integer, the number of notes found by the executed auditors.

Configuration

ExecuteAuditHandler can’t be instantiated or configured directly; instances are created and configured through its definition: ExecuteAuditHandlerDefinition (info.magnolia.services.seo.workflow.ExecuteAuditHandlerDefinition). ExecuteAuditHandlerDefinition will always create an ExecuteAuditHandler instance.

ExecuteAuditHandlerDefinition has several several properties that control how ExecuteAuditHandler is executed in a workflow:

the list of auditors to be executed
the criteria for judging whether the audits were passed or failed.

You can override the configured properties in the ExecuteAuditHandlerDefinition by defining values in the workflow context passed to the ExecuteAuditHandler instance in a workflow. See the configuration properties below.

ExecuteAuditHandlerDefinition can be configured with the following properties:

Property Description

Property	Description
`class`	required, must be `info.magnolia.services.seo.workflow.ExecuteAuditHandlerDefinition`.
`auditors`	required A list of auditor names to be executed. During execution, if the workflow context (`mgnlData`) contains an item named auditors, its list of auditors will be used instead of the configured auditors in the definition.
`failOnErrors`	optional, defaults to `true` If any errors are found by auditors, the audit will be marked as failed. During execution, if the workflow context (`mgnlData`) contains an item named `failOnErrors`, its value will be used instead of the configured `failOnErrors` value.
`failOnWarnings`	optional, defaults to `true` If any warnings are found by auditors, the audit will be marked as failed. During execution, if the workflow context (`mgnlData`) contains an item named `failOnWarnings`, its value will be used instead of the configured `failOnWarnings` value.
`failOnNotes`	optional, defaults to `true` If any notes are found by auditors, the audit will be marked as failed. During execution, if the workflow context (`mgnlData`) contains an item named `failOnNotes`, its value will be used instead of the configured `failOnNotes` value.

class

required, must be info.magnolia.services.seo.workflow.ExecuteAuditHandlerDefinition.

auditors

required

A list of auditor names to be executed.

During execution, if the workflow context (mgnlData) contains an item named auditors, its list of auditors will be used instead of the configured auditors in the definition.

failOnErrors

optional, defaults to true

If any errors are found by auditors, the audit will be marked as failed.

During execution, if the workflow context (mgnlData) contains an item named failOnErrors, its value will be used instead of the configured failOnErrors value.

failOnWarnings

optional, defaults to true

If any warnings are found by auditors, the audit will be marked as failed.

During execution, if the workflow context (mgnlData) contains an item named failOnWarnings, its value will be used instead of the configured failOnWarnings value.

failOnNotes

optional, defaults to true

If any notes are found by auditors, the audit will be marked as failed.

During execution, if the workflow context (mgnlData) contains an item named failOnNotes, its value will be used instead of the configured failOnNotes value.

Example

Here is an example of a configured ExecuteAuditHandler definition from the SEO module. You can find this configuration here: /modules/seo/workItemHandlers/audit.

audit:
  class: info.magnolia.services.seo.workflow.ExecuteAuditHandlerDefinition
  failOnNotes: false
  failOnWarnings: false
  auditors:
    windowTitleDefined:
      value: windowTitleDefined
    windowTitleValid:
      value: windowTitleValid
    titleRendered:
      value: titleRendered
    metaDescriptionDefined:
      value: metaDescriptionDefined
    metaDescriptionValid:
      value: metaDescriptionValid
    metaDescriptionRendered:
      value: metaDescriptionRendered
    metaKeywordsDefined:
      value: metaKeywordsDefined
    metaKeywordsValid:
      value: metaKeywordsValid
    metaKeywordsRendered:
      value: metaKeywordsRendered

AuditNotificationWorkItemHandler

AuditNotificationWorkItemHandler (info.magnolia.services.seo.workflow.AuditNotificationWorkItemHandler) can send notifications about the results of executed audits in a workflow. It can be added after an ExecuteAuditHandler to report the results of an audit.

AuditNotificationWorkItemHandler collects the audit results in auditResults and uses them to format a message subject and body.

You can use placeholders in the title and message body as follows:

Placeholders are formatted using MessageFormat (java.util.MessageFormat), see here for more details.

Placeholder Message

Placeholder	Message
`0`	The node type (e.g., `mgnl:page`) of the audited node.
`1`	The node path of the audited node.
`2`	The audit status, `passed` or `failed`.
`3`	The number of errors found in the audit.
`4`	The number of warnings found in the audit.
`5`	The number of notes found in the audit.

0

The node type (e.g., mgnl:page) of the audited node.

1

The node path of the audited node.

2

The audit status, passed or failed.

3

The number of errors found in the audit.

4

The number of warnings found in the audit.

5

The number of notes found in the audit.

Configuration

AuditNotificationHandler cannot be instantiated or configured directly. You must use NotificationWorkItemHandlerDefinition (info.magnolia.module.workflow.jbpm.workitem.handler.definition.NotificationWorkItemHandlerDefinition) to set up instances of AuditNotificationHandler.

NotificationWorkItemHandlerDefinition has the following properties:

Property Description

Property	Description
`class`	Required, must be `info.magnolia.module.workflow.jbpm.workitem.handler.definition.NotificationWorkItemHandlerDefinition`.
`implementationClass`	Required, must be `info.magnolia.services.seo.workflow.AuditNotificationWorkItemHandler`.
`subject`	Required The message subject. Placeholders as above will be substituted into the subject.
`body`	Required The message body. Placeholders as above will be substituted into the body.

class

Required, must be info.magnolia.module.workflow.jbpm.workitem.handler.definition.NotificationWorkItemHandlerDefinition.

implementationClass

Required, must be info.magnolia.services.seo.workflow.AuditNotificationWorkItemHandler.

subject

Required

The message subject. Placeholders as above will be substituted into the subject.

body

Required

The message body. Placeholders as above will be substituted into the body.

Example

Here is an example of a configured AuditNotificationHandler definition from the SEO module. You can find this configuration here: /modules/seo/workItemHandlers/failedAuditNotification.

failedAuditNotification:
  class: info.magnolia.module.workflow.jbpm.workitem.handler.definition.NotificationWorkItemHandlerDefinition
  implementationClass: info.magnolia.services.seo.workflow.AuditNotificationWorkItemHandler
  message: Found {3} errors, {4} warnings and {5} notes in {0}:{1}. Please correct any problems found before publishing again.
  subject: Audit of {0}:{1} failed!

Workflow integration

ExecuteAuditHandler

Configuration

Example

AuditNotificationWorkItemHandler

Configuration

Example

Location

Main doc sections