Adobe Experience Manager workflow integration guide

The Siteimprove CMS Plugin for Adobe Experience Manager (AEM) includes the ability to integrate Siteimprove checks in AEM workflows. You can notify and/or assign AEM tasks to authors in the publishing process and prevent issues from going live that are important to your site. Automating Siteimprove checks in the publishing process saves you from fixing regressions on live pages.

• Prerequisites
• Content check
• Unpublish check
• Or Split
• Sample Workflow Models
• Workflow Tips

Prerequisites

• Working knowledge of AEM workflows (see Adobe documentation for workflow editing).
• Site is being crawled by Siteimprove
• Siteimprove CMS plugin installed in AEM

The two available Siteimprove checks for AEM workflows are:

1. Content check – see issues on a page
2. Unpublish check – see the impact of unpublishing a page

Content check

A content check is a combination of two Siteimprove workflow steps followed by an Or Split with custom logic to decide what the workflow should do next. It’s commonly used to check a page for business-critical issues before publishing. If a content check fails to meet the standards you’ve set, the workflow item can be reassigned to the page author or another user/group to fix the issues. Once the issues are fixed you can restart the workflow. The content check should then pass and publish the page.

FIGURE 1 – screenshot of content check steps in the AEM workflow editor

Workflow steps

Siteimprove content check process

This step sends the page HTML to Siteimprove for running the Prepublish check. It’s necessary because the page isn’t published yet and therefore can’t be found by a crawler.

FIGURE 2 – Screenshot of content check process step properties

Siteimprove content verification

This step allows you to configure the metrics to check for and the threshold number of issues before the check fails. Available metrics fall into three categories: Policy, Quality Assurance (QA), and Search Engine Optimization (SEO).

FIGURE 3 – Screenshot of content verification step properties

Policy

• High-priority matching policies – matches for active policies marked as high priority in the Siteimprove platform
• Matching Policies – matches for active policies in the Siteimprove platform

Quality Assurance (QA)

• Email addresses – finds email addresses on page for updating or removing
• Languages – detects different languages on page for managing translations
• Link texts – checks if links have text alternatives to describe their purpose
• Links – checks number of links on page 
• Meta tags – detects meta tags included in the page HTML
• Misspellings – finds misspelled words on page
• Personal ID numbers – checks for ID numbers relating to where your account is located (for example, US accounts look for Social Security numbers)
• Phone numbers – finds phone numbers on page for updating or removing
• Potential misspellings – finds jargon terms specific to your company or industry, or people and place names that aren't recognized
• Trademarks – detects trademark usage on page

Search Engine Optimization (SEO)

• Content issues – checks the quality of visitor-facing content with respect to how it engages users, and whether meta content is optimized for search engines and users
• Technical issues – checks how optimized the technical elements of a page are for being crawled and indexed by search engine bots
• UX issues – checks how effectively embedded information, like links and visuals, is used to enhance the user experience

Unpublish check

The Siteimprove Unpublish Check process is a single workflow step in which you can configure what metrics to check relevant to the impact of unpublishing the page.

FIGURE 4 – Screenshot of unpublish check step properties

Available metrics are:

• Amount of Ad Groups
• Amount of Ads
• Amount of Campaigns
• Clicks
• Metrics for related landing pages
• External referring pages from traffic sources for page
• Check if page has behaviour map
• Number of times this page has been viewed
• Potential campaigns for page
• Potential key metrics for page
• Documents on page
• Documents that only appear on this page
• Internal referring pages for page
• Backlinks for page
• Check if page is target page
• Ranking keyword for page

Or split

An Or split workflow step is needed after a content or unpublish check to decide how the workflow will advance based on the check results. Branch 1 is executed when all content verification metrics pass. Branch 2 is executed if at least one of the checks fails. There are two scripts provided (with the plugin installation) to handle the logic for each branch:

Branch 1 = /apps/siteimprove/plugin/ui/workflow/checkNoErrors.ecma
Branch 2 = /apps/siteimprove/plugin/ui/workflow/checkHasErrors.ecma

FIGURE 5 – Screenshot of branch 1 configuration for Or Split step

You can customize how you want each branch to advance from here. For example, in the Siteimprove Content Check Sample Model, Branch 1 publishes the page when the check passes. Branch 2 reassigns the workflow back to the workflow initiator with a notification in their AEM inbox.

From the inbox, the author can open the workflow payload and run a Prepublish check to highlight and fix the issues directly in the page editor. Once the issues are fixed, the author can mark the workflow notification complete, and the workflow would go back to step 1 and re-check the page. When the automated content check passes, the workflow will execute Branch 1 and the page will publish.

Sample Workflow Models

We provide sample workflow models for each Siteimprove check to help you get started. You can edit them to fit your needs or copy the steps you want into an existing workflow.

Tip: Make a copy of a sample workflow for reference before editing. There is not an option to copy workflows in the AEM UI. This would be a request for an AEM developer.

Siteimprove Content Check

The Siteimprove Content Check workflow model checks a page for specific issues and based on the results of the check either publishes the page or reassigns the workflow back to the author to fix the issues.

FIGURE 6 – screenshot of content check sample workflow in AEM editor

The steps are:

1. Run Siteimprove content check process
2. Run Siteimprove content verification process
3. Or Split – Decision if publish or reassign for editing
   (a) Branch 1 publishes the page
   (b) Branch 2 reassigns the workflow back to author to fix the errors
      (i) When the author marks the workflow item complete after fixing errors, the workflow starts the content check process step again.

Siteimprove Unpublish Check

The Siteimprove Unpublish Check workflow model checks the impact of unpublishing a page. Based on the check results it will either unpublish the page or reassign the workflow back to the author for review.

FIGURE 7 – screenshot of unpublish check sample workflow in AEM editor

The steps are:

1. Run Siteimprove unpublish check process
2. Or Split – Decision if unpublish or reassign for review
   a. Branch 1 unpublishes the page
   b. Branch 2 reassigns the workflow back to the author for review

Workflow Tips

Here are a few things to consider for successful workflow customization.

Start from a copy when editing an existing workflow

Even though workflows are versioned it’s always a good idea to make a copy before adding Siteimprove steps. This ensures no issues with workflows in use. 

Place Siteimprove Checks before participant steps

The automated checks are recommended before it’s sent to someone for a manual review. The next step after manual review should be to rerun the automated content check.

Write action-oriented titles and descriptions for participant steps

Instruct the author to open the payload in the participant step description so they know how to take action. From the page editor, you can run a Prepublish check to highlight and fix the issues on a page.

Allow admin groups to bypass workflows when needed

If you make workflows required for page publishing, make sure AEM admins can bypass the workflow and publish immediately when needed.