Custom reporting and automatic owner assignment for annual reviews

Summary

This article outlines how to implement an annual review process in Comala Document Management Cloud when you need to automatically assign the Confluence page owner as a reviewer upon expiry. It covers a workaround for dynamic owner assignment using workflow parameters and provides scalable reporting options to track "Invalid" (expired) pages, their owners, and expiry dates.

Use case: Annual review with dynamic ownership

Problem

A customer needs to implement a simple "Valid/Invalid" review cycle where:

Pages with specific labels expire once per year.
The page creator/owner must be the one to review the page.
The organization requires a scalable overview (400–500 pages) showing which pages are "Invalid," who the owner is, and the expiry date.

Known limitations

Dynamic placeholders: In Comala Document Management Cloud, the @creator@ or @user@ placeholders cannot currently be resolved dynamically within approval assignments or set-metadata actions.
Metadata report limits: The Document Metadata Report macro may appear limited in the number of results displayed by default.

Solution: Workflow parameter workaround

To achieve automatic assignment of the page owner as a reviewer, use a workflow parameter. This ensures the owner's name appears in the standard Document Report.

1. Configure the workflow

Add a parameter to your JSON workflow to capture the owner and use it in the approval assignment for the "Invalid" (expired) state.

{
    "workflow": {
        "parameters": [
            {
                "name": "pageowner",
                "type": "user",
                "scope": "page",
            }
        ],
        "states": [
            {
                "name": "Valid",
                "expiry": "365d",
                "transitions": {
                    "expired": "Invalid"
                }
            },
            {
                "name": "Invalid",
                "approvals": [
                    {
                        "name": "Annual Review",
                        "preassignedUsers": [
                            "@pageowner@"
                        ]
                    }
                ]
            }
        ]
    }
}

Here's a sample Content Expiry Workflow with the above suggestion implemented:

{
  "id": "content-expiry-annual",
  "name": "Annual Content Expiry Workflow",
  "description": "A workflow that moves content to an Invalid state every 365 days and assigns the page owner for review.",
  "parameters": [
    {
      "name": "pageowner",
      "type": "user",
      "scope": "page"
    }
  ],
  "states": [
    {
      "name": "Review",
      "approvals": [
        {
          "name": "Initial Approval",
          "assignable": true
        }
      ],
      "transitions": {
        "approved": "Valid",
        "rejected": "Invalid"
      },
      "colour": "#FFAB00"
    },
    {
      "name": "Valid",
      "final": true,
      "transitions": {
        "expired": "Invalid",
        "updated": "Review"
      },
      "colour": "#14892C"
    },
    {
      "name": "Invalid",
      "approvals": [
        {
          "name": "Annual Review",
          "preassignedUsers": {
            "items": [
              "@pageowner@"
            ]
          },
          "rememberAssignees": true
        }
      ],
      "transitions": {
        "approved": "Valid",
        "updated": "Review"
      },
      "colour": "#FF5630"
    }
  ],
  "triggers": [
    {
      "event": "on-expire",
      "actions": [
        {
          "action": "send-email",
          "recipients": [
            "@pageowner@"
          ],
          "notification": {
            "subject": "[Expiry Alert] ${content.title} requires review",
            "title": "Action Required: Content Expired",
            "body": "The page '${content.title}' has been in the 'Valid' state for 365 days. It has now transitioned to 'Invalid'. Please review the content and approve it to reset the annual clock."
          }
        }
      ]
    }
  ],
  "HTMLdescription": "<h3>Annual Content Expiry</h3><p>Automates the tracking of stale content.</p><ul><li><b>Valid:</b> The content is current. Expires after 365 days.</li><li><b>Invalid:</b> The content is expired. The Page Owner is automatically assigned to review.</li><li><b>Triggers:</b> An email is sent to the Page Owner the moment the content expires.</li></ul>"
}

2. Implementation steps

Set the parameter: When the workflow is first applied to a page, manually set the pageowner parameter once.
Automatic assignment: When the page reaches its 365-day expiry and transitions to the Invalid state, the user assigned to the @pageowner@ parameter is automatically added as the reviewer.
Visibility: Once assigned as a reviewer, the owner's name automatically populates the Reviewer column in the standard reports.

Scalable reporting options

Option A: Standard Document Report (recommended)

By using the parameter workaround above, the Document Report (found in Space Tools > Document Report) becomes the most efficient tool because:

It displays the Workflow State (Valid/Invalid).
It displays the Reviewer (which is now the page owner).
It displays the Due Date (the expiry date).
It handles large volumes of pages more effectively than some macros.

Option B: Page Properties Report

For a fully customized table, combine the Page Properties macro with the Document State macro.

On each page, place a Page Properties macro containing a table with an "Owner" row.
Use the Document State macro to show the status.
Use the Page Properties Report macro on an overview page to aggregate this data.