Approval Types and Step Types

Approval Types and Step Types

This document describes all the available approval types and step types in ApprovalML, and how they behave in workflows.

Step Types

1. decision - Standard Approval Step

• Purpose: Single approver with approve/reject actions
• Behavior: Blocks workflow until action is taken
• Actions Available: Approve, Reject, Request More Information
• Use Case: Manager approvals, final decisions

2. parallel_approval - Multiple Approvers

• Purpose: Multiple approvers can work simultaneously
• Behavior: All approvers must complete (or configured strategy)
• Actions Available: Approve, Reject, Request More Information
• Use Case: Team reviews, committee approvals

3. conditional_split - Dynamic Routing

• Purpose: Route workflow based on form data or conditions
• Behavior: Automatically processes and routes to next step
• Actions Available: None (automatic)
• Use Case: Amount-based routing, department-specific flows

4. automatic - System Processing

• Purpose: System performs actions without human intervention
• Behavior: Automatically completes and continues
• Actions Available: None (automatic)
• Use Case: Data processing, system integrations, notifications

5. notification - Non-blocking Notification

• Purpose: Send notifications without requiring action
• Behavior: Automatically completes and continues
• Actions Available: None (automatic)
• Use Case: FYI notifications, status updates

Approval Types

1. needs_to_approve (Default)

Recipients with this role type… can do the following:

• Approve will move the workflow to the next recipient (if any)
• Decline will send the workflow back to the requestor for re-submission
• Request More Information will also send the workflow back to the requestor for re-submission

YAML Example:

manager_approval:
  name: "manager_approval"
  type: "decision"
  approver: "${requestor.manager}"
  approval_type: "needs_to_approve"  # Optional, this is the default
  on_approve:
    continue_to: "next_step"
  on_reject:
    end_workflow: true

2. needs_to_sign

Recipients with this role type… can do the following:

• Provide Signature will capture the recipient’s signature and move the workflow to the next recipient (if any)
• Decline will send the workflow back to the requestor for re-submission
• Request More Information will also send the workflow back to the requestor for re-submission

YAML Example:

legal_signature:
  name: "legal_signature"
  type: "decision"
  approver: "legal_team"
  approval_type: "needs_to_sign"
  on_approve:
    continue_to: "next_step"
  on_reject:
    end_workflow: true

External/Unregistered Approvers

For external users (vendors, clients, contractors) who don’t have accounts, use the approver object format:

vendor_signature:
  name: "vendor_signature"
  type: "decision"
  approver:
    email: "vendor@external.com"
    name: "Jane Smith"
    position: "Vendor Representative"
    employee_type: "external"  # Options: internal, external, contractor
  approval_type: "needs_to_sign"
  on_approve:
    continue_to: "next_step"
  on_reject:
    end_workflow: true

Features:

• Automatically creates employee record if email doesn’t exist
• No pre-registration required
• Signature stored against employee record
• Supports template variables from form data

Dynamic approvers from form fields:

client_acknowledgement:
  name: "client_acknowledgement"
  type: "decision"
  approver:
    email: "${form.client_email}"
    name: "${form.client_name}"
    position: "${form.client_company}"
    employee_type: "external"
  approval_type: "needs_to_sign"
  on_approve:
    continue_to: "completion"

Signature Display Format:

Before signing:

Signed by ________________

Jane Smith
Vendor Representative • External

After signing:

Signed by [Signature Image/Text]

Jane Smith
Vendor Representative • External
Signed on: March 8, 2026, 10:30 AM

Use Cases:

• Vendor sign-offs on purchase orders
• Client acknowledgements on contracts
• Contractor certifications
• Partner approvals
• Third-party validations

Signature Field Mapping

Link the captured signature to a specific form field using signature_field:

form:
  fields:
    - name: authorized_signature
      type: signature
      label: "Authorized Signature"
      required: true

workflow:
  finance_approval:
    type: decision
    approver: finance_manager
    approval_type: needs_to_sign
    signature_field: authorized_signature  # Maps signature to this form field
    on_approve:
      continue_to: approved_end

How it works:

• When the approver signs, their signature automatically populates the specified form field
• The form field must be of type signature
• The signature is stored both in the approval step and in the form data
• Useful for contracts requiring multiple specific signatures in designated locations

Example with multiple signature fields:

form:
  fields:
    - name: manager_signature
      type: signature
      label: "Manager Signature"
    - name: director_signature
      type: signature
      label: "Director Signature"
    - name: legal_signature
      type: signature
      label: "Legal Department Signature"

workflow:
  manager_review:
    approver: department_manager
    approval_type: needs_to_sign
    signature_field: manager_signature  # Populates manager_signature field
    on_approve:
      continue_to: director_review

  director_review:
    approver: director
    approval_type: needs_to_sign
    signature_field: director_signature  # Populates director_signature field
    on_approve:
      continue_to: legal_review

  legal_review:
    approver: legal_team
    approval_type: needs_to_sign
    signature_field: legal_signature  # Populates legal_signature field
    on_approve:
      end_workflow: true

3. needs_to_recommend

Recipients with this role type… can do the following:

• Recommend will move the workflow to the next recipient (if any)
• Not Recommend will also move the workflow to the next recipient (if any)
• Request More Information will send the workflow back to the requestor for re-submission

Note: This role is designed specifically for recipients that do not have authority to decline a request. If you want the recipient to be able to decline the request back to the requestor, use the needs_to_approve role instead.

YAML Example:

finance_review:
  name: "finance_review"
  type: "decision"
  approvers:
    - role: "finance_manager"
      approval_type: "needs_to_recommend"
    - role: "budget_analyst"
      approval_type: "needs_to_recommend"
  # Important: define both paths to keep flow moving
  on_approve:
    continue_to: "next_step"
  on_reject:        # when they choose Not Recommend
    continue_to: "next_step"  # Still proceeds

4. needs_to_acknowledge

Non-blocking — the workflow continues immediately to the next step. The step stays pending in the background so the assignee can acknowledge at any time, and the acknowledgement timestamp is recorded in the audit trail.

Recipients with this role type… can do the following:

• Acknowledge records a timestamp and marks the step complete (workflow has already moved on)
• Request More Information sends the workflow back to the requestor for re-submission

YAML Example:

policy_acknowledgment:
  name: "policy_acknowledgment"
  type: "decision"
  approver: "${requestor.supervisor}"
  approval_type: "needs_to_acknowledge"
  on_approve:
    continue_to: "next_step"

Key behaviours:

• Email is sent to the assignee the moment the step is created
• Workflow does not wait — it advances to on_approve.continue_to immediately
• The assignee can acknowledge before or after the workflow completes
• If they never acknowledge, the step remains pending in the DB — useful as a compliance record showing they were notified
• Use this when you want an audit trail of who was informed, not when you need a gate

See Acknowledgement Steps for placement guidance and examples.

5. needs_to_call_action

Recipients with this role type… can do the following:

• Complete Action will execute the action and move to the next workflow node
• Fail Action will go back to the previous node
• Request More Information will send the workflow back to the requestor for re-submission

Note: This can be an API call or manual task. If it’s a manual task, the action creates the task, and once the task is completed, it proceeds. If it’s an API call, on success it moves to the next workflow node, if it fails, it goes back to the previous node.

YAML Example:

it_action:
  name: "it_action"
  type: "decision"
  approver: "it_team"
  approval_type: "needs_to_call_action"
  on_approve:
    continue_to: "next_step"
  on_reject:
    continue_to: "next_step"  # Action completed

6. receives_a_copy

Recipients with this role type… receive a copy of the request only. No action is required.

YAML Example:

stakeholder_notification:
  name: "stakeholder_notification"
  type: "decision"
  approvers:
    - role: "requestor"
      approval_type: "receives_a_copy"
    - role: "department_head"
      approval_type: "receives_a_copy"
  on_complete:
    continue_to: "next_step"

Non-blocking Steps

notification Step Type

This step type automatically completes without requiring any action:

notify_supervisor:
  name: "notify_supervisor"
  type: "notification"
  description: "Supervisor receives notification of request"
  recipients:
    - email: "${requestor.supervisor_email}"
  notification:
    message:
      subject: "Request Submitted"
      body: "A new request has been submitted by your team member."
  on_complete:
    continue_to: "next_step"

receives_a_copy Approval Type

This approval type automatically completes without requiring any action:

stakeholder_copy:
  name: "stakeholder_copy"
  type: "decision"
  approver: "stakeholders"
  approval_type: "receives_a_copy"
  on_complete:
    continue_to: "next_step"

Step-Level Options for Decision Steps

These fields apply to type: decision steps regardless of the approval_type chosen.

require_login

Controls whether the email approval link requires the approver to be logged in.

Value	Email link sent	Best for
false (default)	Public token — approve/reject directly, no login	External approvers, vendors, clients
true	Authenticated URL — must sign in first	Internal high-security steps, MFA/SSO-enforced decisions

# External vendor — no login needed (default)
vendor_approval:
  name: "Vendor Sign-off"
  type: "decision"
  approver:
    email: "${form.vendor_email}"
    name: "${form.vendor_name}"
    employee_type: "external"
  approval_type: "needs_to_sign"
  on_approve:
    continue_to: "procurement"

# Internal security review — login enforced
security_review:
  name: "Security Officer Review"
  type: "decision"
  approver: "security_officer"
  require_login: true
  on_approve:
    continue_to: "deployment"
  on_reject:
    end_workflow: true

Best Practices

1. Use notification for pure FYI notifications that shouldn’t block the workflow
2. Use receives_a_copy when you want to send copies but still have a step in the workflow
3. Use needs_to_recommend for advisory roles that shouldn’t have veto power
4. Use needs_to_sign for legal or compliance requirements
5. Use needs_to_call_action for steps that require system integration or manual task completion
6. Use needs_to_acknowledge when you need confirmation but don’t need full approval
7. Use require_login: true on sensitive internal steps to enforce authentication before the approver can act; omit it (default false) for external approvers who receive public token links

Example Workflow with Mixed Types

workflow:
  # Non-blocking notification
  notify_supervisor:
    type: "notification"
    recipients:
      - email: "${requestor.supervisor_email}"
    notification:
      message:
        subject: "Request Submitted"
        body: "A new request has been submitted."
    on_complete:
      continue_to: "manager_approval"

  # Standard approval
  manager_approval:
    type: "decision"
    approver: "${requestor.manager}"
    approval_type: "needs_to_approve"
    on_approve:
      continue_to: "finance_review"
    on_reject:
      end_workflow: true

  # Advisory review
  finance_review:
    type: "decision"
    approver: "finance_team"
    approval_type: "needs_to_recommend"
    on_approve:
      continue_to: "legal_signature"
    on_reject:
      continue_to: "legal_signature"  # Proceeds regardless

  # Legal signature
  legal_signature:
    type: "decision"
    approver: "legal_team"
    approval_type: "needs_to_sign"
    on_approve:
      continue_to: "completion"
    on_reject:
      end_workflow: true

  # Copy to stakeholders
  completion:
    type: "decision"
    approvers:
      - role: "requestor"
        approval_type: "receives_a_copy"
      - role: "department_head"
        approval_type: "receives_a_copy"
    on_complete:
      end_workflow: true