Read acknowledgment

Overview

A small proof-of-concept template, reusable for any “N users must confirm they have read a document” flow. A master workflow, started manually on a document, launches one child review per reviewer in parallel; once every child has confirmed, the master closes the loop and stamps the document as fully read.

Download master workflow: read-acknowledgment.okmflow

Download slave workflow: read-acknowledgment-review.okmflow

Diagram

Master

Slave

How it works

1. The master (read-acknowledgment) is started manually on a document. It fetches every user with ROLE_SUPERVISOR and launches one read-acknowledgment-review child per user, in parallel.
2. Each child shows the document to its reviewer with a single “Yes, I have read it” button and an optional comment.
3. When a reviewer confirms, the child adds a note to the document (comment, plus who read it and when) and reports back to the master, then ends.
4. Meanwhile the master waits on a task assigned to the system user. A scheduled action polls how many reviewers have reported back; once all of them have, it releases the wait and the master finalizes, stamping the document as fully read.

Communication between workflows (context)

The master and its children never share a document field for this — they only talk to each other through process-instance context variables.

Variable	Set by	Read by
uuid, reviewer, initiator, srcProcInsId	Master, when launching each child	Child — identifies which document/user pair it handles and which master instance to report back to.
pendingReviewers, pendingTotal	Master, right after launching all the children	Master’s own scheduled action — the list/count it checks progress against.
status_<reviewer>	Each child, once its reviewer confirms — written directly into the master’s process instance	Master’s scheduled action — counts how many reviewers have answered.

A scheduled action node (name starting with scheduled) attached to the master runs on a timer and compares confirmations received against pendingTotal; once they match, it releases the master’s waiting task so it can finalize.

Prerequisites

Before deploying this workflow, the following must exist in OpenKM.

Users and roles

Identifier	Type	Used in	Description
ROLE_SUPERVISOR	Role	Notify all admins	Every user with this role receives a read task in parallel — no pool/self-assign, each gets their own child process. Must have at least one user assigned besides the initiator; if none exist, the master’s Notify all admins action fails immediately.

Metadata group

The property group okg:read_acknowledgment must be registered in OpenKM before the first execution — it is not created automatically by deploying the .okmflow files, and ws.propertyGroup.addGroup(...) fails the first time a document is processed if it is missing. It is applied programmatically by the master (Notify all admins and Finalize) — the user never fills it in. The definition to import is metadata.xml, alongside the two .okmflow files in the template folder:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.12//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.12.dtd">
<property-groups>
  <property-group label="Read acknowledgment" name="okg:read_acknowledgment">
    <select label="Reading status" name="okp:read_acknowledgment.status" type="simple" readonly="true">
      <option label="Pending" value="Pending" />
      <option label="All read" value="All read" />
    </select>
  </property-group>
</property-groups>

Single read-only field, status: set to Pending as soon as the master launches the child reviews, flipped to All read by Finalize once the last confirmation comes in.