Skip to content
Aptiwise Documentation

Role Fields Reference

Role Fields Reference

Section titled “Role Fields Reference”

Aptiwise employees have three distinct role fields. Mixing them up is a common source of permission bugs — this page explains exactly what each field does and when to use it.

Quick Reference

Section titled “Quick Reference”
FieldTypeUsed forNever use for
approval_rolestext[]Matching employees to workflow approval stepsDisplay / org chart
company_rolestext[]Controlling who can start (submit) a workflowApproval permission checks
roletextDisplaying a job title in the UIAny logic or matching

approval_roles — Who Can Approve a Step

Section titled “approval_roles — Who Can Approve a Step”

This array determines which workflow steps an employee can act on as an approver.

# Workflow step
review_step:
  name: "Engineering Review"
  type: "decision"
  approver: "engineering_manager"   # matched against approval_roles
  approval_type: "needs_to_approve"
# Employee record — this person can approve the step above
{
    "name": "Alice",
    "approval_roles": ["engineering_manager", "budget_approver"]
}

Key points:

  • Checked by the backend on every approval action and by the frontend to decide which action buttons to show
  • Matching is case-insensitive — "Direktur" matches "direktur"
  • An employee can hold multiple approval roles
  • Use specific, workflow-oriented labels (not org-chart titles)

SQL pattern used internally:

WHERE LOWER($1) = ANY(ARRAY(SELECT LOWER(r) FROM UNNEST(approval_roles) AS r))

company_roles — Who Can Submit a Workflow

Section titled “company_roles — Who Can Submit a Workflow”

This array controls submission access — which employees are allowed to start a particular workflow.

# Workflow submission criteria
submission_criteria:
  company_roles:
    - "department_manager"
    - "team_lead"

Only employees whose company_roles overlaps the workflow’s submission_criteria.company_roles list can see and submit that workflow.

Key points:

  • Only used in submission_criteria — never in approval step matching
  • Represents organizational position / hierarchy level
  • An employee can hold multiple company roles

role — Display Label Only

Section titled “role — Display Label Only”

A single string holding the employee’s human-readable job title. It has no functional effect on approvals or submissions.

{ "role": "Senior Engineering Manager" }   # shown in the UI, that's all

Do not reference this field in workflow YAML, approval logic, or submission criteria.

Case-Insensitive Matching

Section titled “Case-Insensitive Matching”

All role matching (both approval_roles and company_roles) is case-insensitive. This prevents typos from silently breaking workflows when roles come from different sources.

"Direktur" == "direktur" == "DIREKTUR"  ✓
"Finance_Approver" == "finance_approver"  ✓

Complete Employee Record Example

Section titled “Complete Employee Record Example”
{
    "email": "alice@company.com",
    "name": "Alice Manager",
    "role": "Senior Engineering Manager",       # display only
    "approval_roles": [
        "engineering_manager",                  # can approve Engineering Review steps
        "budget_approver"                       # can approve budget steps
    ],
    "company_roles": [
        "department_manager",                   # can submit Dept. workflows
        "head_of_engineering"                   # can submit Eng. workflows
    ]
}

Workflow Configuration Examples

Section titled “Workflow Configuration Examples”

Approval step using approval_roles

Section titled “Approval step using approval_roles”
workflow:
  manager_review:
    name: "Manager Review"
    type: "decision"
    approver: "engineering_manager"     # resolved against approval_roles
    approval_type: "needs_to_approve"
    on_approve:
      continue_to: "finance_review"
    on_reject:
      end_workflow: true

Submission restriction using company_roles

Section titled “Submission restriction using company_roles”
submission_criteria:
  company_roles:
    - "department_manager"
    - "ceo"
# Only employees with one of these company_roles can submit this workflow

Combining both in one workflow

Section titled “Combining both in one workflow”
submission_criteria:
  company_roles: ["department_manager"]   # who can START


workflow:
  manager_approval:
    approver: "department_manager"        # who can APPROVE (approval_roles)
    approval_type: "needs_to_approve"

Note that "department_manager" appears in both contexts — but they are checked against different fields on the employee record. A submitter has it in company_roles; an approver has it in approval_roles. These are independent and an employee can have it in both, one, or neither.

See also: