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

(warning) Added in v5.6.1

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

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: 

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.

errorsInteger, the number of errors found by the executed auditors
warningsInteger, the number of warnings found by the executed auditors
notesInteger, 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:

classrequired, 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: 

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.

Placeholders are formatted using MessageFormat (java.util.MessageFormat), see https://docs.oracle.com/javase/8/docs/api/java/text/MessageFormat.html for more. 

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: 

classRequired, must be info.magnolia.module.workflow.jbpm.workitem.handler.definition.NotificationWorkItemHandlerDefinition
implementationClassRequired, 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!