Skip to content
Aptiwise Documentation

Acknowledgement Steps

Acknowledgement Steps

Section titled “Acknowledgement Steps”

Acknowledgement steps (approval_type: needs_to_acknowledge) let a workflow notify someone and record that they saw it — without blocking the workflow while waiting for their response.

How They Work

Section titled “How They Work”

When an acknowledgement step is created:

  1. An email is sent to the assignee immediately
  2. The workflow continues to the next step right away — it does not wait
  3. The step remains pending in the system so the assignee can acknowledge at any time
  4. When they click Acknowledge, the timestamp is recorded in the audit trail

The assignee can acknowledge before the workflow completes, after it completes, or not at all. If they never acknowledge, the step stays pending — a compliance record proving they were notified.

needs_to_acknowledge vs type: notification

Section titled “needs_to_acknowledge vs type: notification”

Both are non-blocking, but they serve different purposes:

| | needs_to_acknowledge | type: notification | |---|---|---| | Requires action | Yes (optional click) | No (auto-completes) | | Timestamp recorded | Yes | No | | Appears in approver's task list | Yes | No | | Compliance audit trail | Yes | No | | Best for | Tracking who was informed | Pure FYI broadcast |

Use needs_to_acknowledge when you need proof of notification. Use type: notification for broadcast announcements where tracking individual read receipts is unnecessary.

Before or After Approval?

Section titled “Before or After Approval?”

The most important placement decision. A simple rule:

Before approval = the acknowledgee's awareness helps the approver make a better decision.
After approval = you're communicating an outcome, not soliciting input.

Place BEFORE approval when…

Section titled “Place BEFORE approval when…”

The acknowledgee's awareness informs the decision

workflow:
  # Legal gets an early look (non-blocking) — CEO sees if legal flagged anything
  legal_review:
    name: "Legal Advisory Review"
    type: "decision"
    approver: "legal_team"
    approval_type: "needs_to_acknowledge"
    on_approve:
      continue_to: "ceo_approval"


  ceo_approval:
    name: "CEO Approval"
    type: "decision"
    approver: "ceo"
    approval_type: "needs_to_approve"
    on_approve:
      end_workflow: true

The acknowledgee can start preparing while approval is in progress

# IT checks inventory availability while manager reviews — speeds up overall process
it_availability_check:
  type: "decision"
  approver: "it_team"
  approval_type: "needs_to_acknowledge"
  on_approve:
    continue_to: "manager_approval"

Place AFTER approval when…

Section titled “Place AFTER approval when…”

You're communicating a decision that has already been made

# Policy change: employees only notified after HR approves
hr_approval:
  type: "decision"
  approver: "hr_director"
  approval_type: "needs_to_approve"
  on_approve:
    continue_to: "employee_notification"


employee_notification:
  type: "decision"
  approver: "all_employees"
  approval_type: "needs_to_acknowledge"
  on_approve:
    end_workflow: true

You need a compliance record of who was informed of an approved outcome

# Safety protocol: track every team member's acknowledgement after approval
safety_approval:
  type: "decision"
  approver: "safety_officer"
  approval_type: "needs_to_approve"
  on_approve:
    continue_to: "team_acknowledgement"


team_acknowledgement:
  type: "decision"
  approver: "all_team_members"
  approval_type: "needs_to_acknowledge"

Decision Framework

Section titled “Decision Framework”
Does the acknowledgee's awareness help the approver decide?
│
├── YES → BEFORE approval
│         (their input or preparation benefits the decision)
│
└── NO → Is this about communicating an outcome?
          │
          ├── YES → AFTER approval
          │         (notify stakeholders of a decision already made)
          │
          └── NO → BEFORE approval
                    (early coordination / heads-up)

When in doubt: default to AFTER approval. About 70% of acknowledgement use cases communicate outcomes rather than inform decisions.

Common Anti-Patterns

Section titled “Common Anti-Patterns”

Notifying before approval when rejection wastes the notified party's effort

Section titled “Notifying before approval when rejection wastes the notified party's effort”
# BAD: IT starts preparing equipment before approval
it_preparation:
  approval_type: "needs_to_acknowledge"
  description: "IT starts sourcing equipment"
  on_approve:
    continue_to: "manager_approval"


manager_approval:
  approval_type: "needs_to_approve"
  on_reject:
    end_workflow: true  # IT just wasted their time

Fix: move the IT step after approval.

Using acknowledgement as a gate

Section titled “Using acknowledgement as a gate”

If the workflow should genuinely wait for a response, use needs_to_approve instead. Acknowledgement steps cannot block the workflow — that is by design.

Too many acknowledgements before any approval

Section titled “Too many acknowledgements before any approval”

Multiple pre-approval notifications cause information overload and wasted effort if the request is ultimately rejected. Consolidate or move them post-approval.

Real-World Example: Equipment Request

Section titled “Real-World Example: Equipment Request”
workflow:
  # BEFORE: IT checks inventory while manager reviews (speeds up process)
  it_availability_check:
    name: "IT Availability Check"
    type: "decision"
    approver: "it_team"
    approval_type: "needs_to_acknowledge"
    description: "IT confirms equipment is available or flags lead time"
    on_approve:
      continue_to: "manager_approval"


  # GATE: Manager decides
  manager_approval:
    name: "Manager Approval"
    type: "decision"
    approver: "${requestor.manager}"
    approval_type: "needs_to_approve"
    on_approve:
      continue_to: "requestor_confirmation"
    on_reject:
      end_workflow: true


  # AFTER: Requestor confirms delivery details once approved
  requestor_confirmation:
    name: "Delivery Confirmation"
    type: "decision"
    approver: "${requestor}"
    approval_type: "needs_to_acknowledge"
    description: "Requestor confirms delivery location and preferred date"

Real-World Example: Policy Change (Cascading)

Section titled “Real-World Example: Policy Change (Cascading)”
workflow:
  hr_approval:
    type: "decision"
    approver: "hr_director"
    approval_type: "needs_to_approve"
    on_approve:
      continue_to: "manager_notification"
    on_reject:
      end_workflow: true


  # Managers acknowledge first
  manager_notification:
    type: "decision"
    approver: "all_managers"
    approval_type: "needs_to_acknowledge"
    description: "Managers review and acknowledge new policy before employees are informed"
    on_approve:
      continue_to: "employee_notification"


  # Then all employees
  employee_notification:
    type: "decision"
    approver: "all_employees"
    approval_type: "needs_to_acknowledge"
    description: "Employees confirm they have read the updated policy"

Cascading acknowledgements (managers → employees) create a clear compliance trail showing the correct communication sequence was followed.

See also: