Purchase order

Overview

The Purchase Order workflow automates the full lifecycle of a purchase requisition: from the initial request submission, through budget validation and management approval, to the formal issuance of the purchase order and email notification of the outcome.

Download: purchase-order.okmflow 

Supported execution paths:

• Direct approval: the request passes Budget Validation and Manager Approval without issues and a purchase order is issued.
• Clarification loop: the budget validator returns the request to the requester for corrections. The request can loop back to Budget Validation as many times as needed.
• Rejection at Budget Validation: the budget validator rejects the request — the requester is notified by email and the process ends.
• Rejection at Manager Approval: the manager rejects the request — the requester is notified by email and the process ends.

Diagram

Prerequisites

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

Database

A custom counter table must be created in the OpenKM database before the first workflow execution:

CREATE TABLE IF NOT EXISTS APP_COUNTER (
    counter_key   VARCHAR(50)  NOT NULL,
    counter_value INT          NOT NULL DEFAULT 1,
    CONSTRAINT pk_app_counter PRIMARY KEY (counter_key)
);

INSERT INTO APP_COUNTER (counter_key, counter_value)
VALUES ('purchase_order', 1);

The table is generic and can be reused by other workflows by adding new rows with different counter_key values.

Users and roles

Metadata group

The property group okg:purchase_order must be registered in OpenKM before the first execution. It is applied automatically to the PO record by the workflow — the user never fills it in manually.

<?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="Purchase Order Request" name="okg:purchase_order" readonly="true">

    <input label="PO Reference"     name="okp:purchase_order.poNumber" />
    <input label="Request Title"    name="okp:purchase_order.requestTitle" />
    <select label="Department"      name="okp:purchase_order.department" type="simple">
      <option label="IT"         value="it"/>
      <option label="Finance"    value="finance"/>
      <option label="Operations" value="operations"/>
      <option label="Sales"      value="sales"/>
      <option label="HR"         value="hr"/>
    </select>
    <input label="Request Date"     name="okp:purchase_order.requestDate" type="date" />
    <input label="Estimated Amount" name="okp:purchase_order.estimatedAmount" />
    <select label="Currency"        name="okp:purchase_order.currency" type="simple">
      <option label="EUR" value="EUR"/>
      <option label="USD" value="USD"/>
      <option label="GBP" value="GBP"/>
    </select>
    <input label="Actual Amount"    name="okp:purchase_order.actualAmount" />
    <select label="Priority"        name="okp:purchase_order.priority" type="simple">
      <option label="Low"    value="low"/>
      <option label="Medium" value="medium"/>
      <option label="High"   value="high"/>
      <option label="Urgent" value="urgent"/>
    </select>
    <input label="Required By Date"    name="okp:purchase_order.requiredByDate" type="date" />
    <input label="Vendor / Supplier"   name="okp:purchase_order.vendor" />
    <textarea label="Justification"    name="okp:purchase_order.description" dbColumnSize="1024" />
    <input label="Official PO Number"  name="okp:purchase_order.poOfficialNumber" />
    <input label="Expected Delivery"   name="okp:purchase_order.deliveryDate" type="date" />
    <select label="Status"             name="okp:purchase_order.status" type="simple">
      <option label="Pending Budget Validation" value="pending_budget"/>
      <option label="Clarification Required"    value="clarification"/>
      <option label="Pending Manager Approval"  value="pending_approval"/>
      <option label="Rejected - Budget"         value="rejected_budget"/>
      <option label="Rejected - Manager"        value="rejected_manager"/>
      <option label="Approved"                  value="approved"/>
      <option label="Issued"                    value="issued"/>
    </select>

  </property-group>
</property-groups>

The group is readonly="true" — all writes are performed programmatically from Action nodes in the workflow.

Repository structure

The action Create PO folder (the first node after Start) builds the following structure in the OpenKM repository each time a new workflow instance is launched:

/okm:root/
  - Purchase Order Request/
      - {year}/                     - Folder (type: folder)
          - PO-{year}-{NNN}/        - Record (type: record) - the main expediente
              - others/             - Folder (type: folder) - for non-budget documents

PO Reference format: PO-{year}-{NNN} where NNN is a zero-padded 3-digit sequential number (e.g. PO-2026-001, PO-2026-002). The counter is read from APP_COUNTER.counter_key = 'purchase_order', incremented, and saved back atomically at workflow start.

The PO record (PO-{year}-{NNN}) is the main container for the purchase order. The workflow process instance is linked to this record via WorkflowUtils.setProcessInstanceNode(context, recordUuid), so the workflow is accessible directly from the document explorer.

Document destinations inside the record:

Node reference

Start

Launches the workflow. No form is presented to the user at this point — the process starts immediately and transitions to the Create PO folder action.

Create PO folder - Action

Runs immediately after Start. Performs all repository initialisation for the new request:

1. Reads the current counter value from APP_COUNTER (counter_key = 'purchase_order'), builds the PO reference string (PO-{year}-{NNN}), and increments the counter.
2. Creates the year folder /okm:root/Purchase Order Request/{year} if it does not already exist (folder type).
3. Creates the PO record PO-{year}-{NNN} inside the year folder using ws.record.create(fldUuid, poNumber, "", 0) (record type).
4. Creates the others subfolder inside the record using ws.folder.create(recordUuid, "others").
5. Stores the following objects in the workflow context for use by subsequent nodes.

Finally, it links the process instance to the PO record via WorkflowUtils.setProcessInstanceNode(context, recordUuid).

Request Submission - Task

Assignment: the workflow initiator (initiator.getId()).

The requester fills in the purchase request details and uploads the supporting documents.

Save metadata - Action

Runs immediately after Request Submission. Reads all form values from context and writes them as metadata properties on the PO record (okg:purchase_order group).

Notable behaviour:

• requestDate is captured automatically using ISO8601.formatBasic(Calendar.getInstance()) — it reflects the moment the requester submitted the form, not when the workflow started. This field is designed for reporting.
• status is set to pending_budget.
• After writing the metadata, the action retrieves the UUID of the budget document by calling ws.document.getChildren(recordUuid).get(0).getUuid() (the record contains exactly one document at this point — the budget file uploaded in the previous task). This UUID is stored as budgetDocumentUuid in context.
• The UUID of the others folder is wrapped as an Input object and stored as othersFolderUuid in context.

Both budgetDocumentUuid and othersFolderUuid are used as type="folder" read-only fields in Budget Validation, Clarification Request, Manager Approval, and Purchase Order tasks, giving every reviewer direct access to the documents from the task form.

Budget Validation - Task

Assignment logic (smart re-assignment):

1. Query task history: WorkflowUtils.getTaskInstances(piId, "Budget Validation")
2. If a previous instance with an assigned actor exists → return that actor (String)
   (ensures the same person handles the re-entry after a Clarification loop)
3. If first time:
   - estimatedAmount < 3000 → return pool of ROLE_FINANCE users (List<String>)
   - estimatedAmount >= 3000 → return "financeManager" (String)

The < 3,000 threshold routes the task to any available member of ROLE_FINANCE as a pool — any member must self-assign it. For amounts greater than or equal to €3,000, it goes directly to financeManager. To modify the threshold or add additional tiers, update the assignExpr of this node.

The form shows all request details in read-only mode, plus two node reference fields:

Set status - Clarification - Action

Updates okp:purchase_order.status to clarification on the PO record.

Also prepares the updateBudgetDocument Upload object for the Clarification Request task:

Input budgetDocumentUuidInput = (Input) context.get("budgetDocumentUuid");
Upload updateBudgetUpload = new Upload();
updateBudgetUpload.setType("update");
updateBudgetUpload.setDocumentUuid(budgetDocumentUuidInput.getValue());
context.put("updateBudgetDocument", updateBudgetUpload);

This allows the requester to upload a new version of the budget document (replacing the original, not creating a duplicate) directly from the Clarification Request form.

Clarification Request - Task

Assignment: the workflow initiator (initiator.getId()).

The requester sees the reviewer's comments and can correct any aspect of the request before resubmitting. All request fields are editable and pre-populated from context.

Notable features of this task:

• Replace Budget Document (type="update") — uploads a new version of the budget document that was submitted in Request Submission, replacing it in-place in the repository. The document UUID is the same; only the content changes (new version created).
• Other Supporting Documents (type="create", multiple) — uploads additional files to the others subfolder. New files are added alongside any previously uploaded files; nothing is deleted.
• The Budget Reviewer Comments field is shown in read-only mode so the requester can see exactly what needs to be corrected.

Set status - Pending Budget - Action

Updates okp:purchase_order.status to pending_budget on the PO record, then routes back to Budget Validation.

Set status - Pending Approval - Action

Updates okp:purchase_order.status to pending_approval on the PO record, then routes to Manager Approval.

Manager Approval - Task

Assignment logic (department-based):

To add a department or change its manager, update the assignExpr of this node.

The form shows the full request in read-only mode, including budget reviewer comments and the two document reference fields (budgetDocumentUuid, othersFolderUuid).

Set status - Approved - Action

Updates okp:purchase_order.status to approved on the PO record, then routes to Purchase Order.

Purchase Order - Task

Assignment: the same user who handled the Budget Validation task, looked up via task history:

WorkflowUtils.getTaskInstances(piId, "Budget Validation")
→ return t.getActor();  // String → direct assignment

This means the finance team member who validated the budget also formalises the purchase order. If no previous actor is found (should not occur in normal flow), the task falls back to okmAdmin.

The form shows the full request summary in read-only mode (including manager comments and document references), followed by editable fields for the purchase order details:

Set status - Issued - Action

Updates okp:purchase_order.status to issued on the PO record.

Also converts the deliveryDate field value (stored internally as yyyyMMddHHmmss) to yyyy-MM-dd format for the notification email:

SimpleDateFormat raw = new SimpleDateFormat("yyyyMMddHHmmss");
SimpleDateFormat fmt = new SimpleDateFormat("yyyy-MM-dd");
Input deliveryDateRaw = (Input) context.get("deliveryDate");
Input deliveryDateFmt = new Input();
deliveryDateFmt.setValue(fmt.format(raw.parse(deliveryDateRaw.getValue())));
context.put("deliveryDate_fmt", deliveryDateFmt);

The Mail node accesses the formatted value via ${deliveryDate_fmt.value}.

Mail - Rejected by Budget - Mail

Sent when the budget validator clicks Reject.

Mail - Rejected by Manager - Mail

Sent when the manager clicks Reject.

Mail - PO Issued - Mail

Sent when the purchasing team issues the purchase order.

End

Single convergence point for all terminal paths (approved + issued, rejected by budget, rejected by manager).

Metadata lifecycle

The okp:purchase_order.status field is updated automatically at each stage transition. The complete lifecycle is:

pending_budget  →  clarification  →  pending_budget  (loop, repeatable)
pending_budget  →  rejected_budget                   (terminal)
pending_budget  →  pending_approval
pending_approval → rejected_manager                  (terminal)
pending_approval → approved
approved        → issued                             (terminal)

The requestDate field is set once at Save metadata and never updated again. It reflects when the requester submitted the form, making it reliable for reporting.

Key patterns