Developer Handover Pack

Developer Handover Pack

Expense Management Automation

This agent handles the first stage of the automated pipeline. On each new Expensify claim submission it reads the attached receipt image or PDF using OCR, extracts the structured fields (amount, date, merchant name, currency, and expense category), and immediately runs each field through the configured expense policy rule set. Claims that pass all rules are marked as verified and handed off to the next agent. Claims that fail are flagged with a specific machine-readable reason code and a human-readable description, and an automated receipt chase email is dispatched via Gmail. This agent eliminates the manual receipt-checking, chasing, and policy-review steps that currently consume the largest share of finance admin time. Estimated build time: 10 hours. Complexity: Moderate.

// Input
expensify.claim {
  claim_id: string,
  employee_email: string,
  submission_timestamp: ISO8601,
  amount: float,
  currency: string,
  merchant_name: string,
  merchant_category: string,
  receipt_url: string | null,
  description: string
}

// Output (passing claim)
verified_claim {
  claim_id: string,
  employee_email: string,
  amount_usd: float,
  merchant_name: string,
  merchant_category: string,
  receipt_gdrive_url: string,
  policy_verdict: 'pass',
  extracted_date: ISO8601
}

// Output (failing claim)
flagged_claim {
  claim_id: string,
  employee_email: string,
  policy_verdict: 'fail',
  flag_reason_code: string,   // e.g. 'MISSING_RECEIPT' | 'OVER_LIMIT' | 'CATEGORY_DISALLOWED'
  flag_reason_human: string,
  chase_email_sent: boolean,
  chase_timestamp: ISO8601
}

This agent receives a verified claim record from the Receipt Extraction and Policy Agent and performs two tasks: it maps the merchant category and description to the correct Xero general ledger code using a pre-built merchant-to-GL mapping table, then creates and populates a draft spend money record in Xero with all fields pre-filled and the receipt file attached. The agent replaces the manual GL coding step and the manual Xero data entry step, which together account for 11 minutes of admin time per claim. The mapping table is maintained as a configuration file outside the agent logic so it can be updated by the finance team without modifying the build. Estimated build time: 8 hours. Complexity: Moderate.

// Input
verified_claim {
  claim_id: string,
  employee_email: string,
  amount_usd: float,
  merchant_name: string,
  merchant_category: string,
  receipt_gdrive_url: string,
  policy_verdict: 'pass',
  extracted_date: ISO8601
}

// GL mapping lookup
gl_mapping_table[merchant_category] -> {
  xero_account_code: string,  // e.g. '420' for Travel, '425' for Meals
  xero_account_name: string,
  tax_type: string            // e.g. 'NONE' | 'TAX'
}

// Output
xero_draft_record {
  xero_transaction_id: string,
  claim_id: string,
  status: 'DRAFT',
  contact_name: string,       // employee full name from Expensify profile
  date: ISO8601,
  amount: float,
  account_code: string,
  account_name: string,
  description: string,
  receipt_attachment_url: string,
  reference: string           // claim_id as Xero reference field
}

This agent takes a confirmed Xero draft record and manages the full approval lifecycle: it identifies the correct approving manager based on a configurable manager assignment matrix (by department or cost centre), sends a structured Slack message with claim details and interactive approve or reject buttons, fires a 24-hour reminder if no action is taken, finalises the Xero record to 'AUTHORISED' status on approval, adds the reimbursement line to the employee's next Gusto payroll run, and sends a confirmation email to the employee via Gmail. On rejection, it posts the rejection reason back to the finance admin via Slack and sends the employee a rejection notification via Gmail. Estimated build time: 10 hours. Complexity: Moderate.

// Input
xero_draft_record {
  xero_transaction_id: string,
  claim_id: string,
  contact_name: string,
  employee_email: string,
  date: ISO8601,
  amount: float,
  account_code: string,
  account_name: string,
  description: string,
  receipt_attachment_url: string
}

// Manager assignment lookup
manager_matrix[employee_email | department] -> {
  manager_slack_id: string,
  manager_email: string
}

// On approval
approval_payload {
  claim_id: string,
  xero_transaction_id: string,
  approved_by_slack_id: string,
  approval_timestamp: ISO8601
}
-> xero.updateTransaction(status: 'AUTHORISED')
-> gusto.addReimbursementLine {
     employee_id: string,
     amount: float,
     description: string,   // 'Expense reimbursement: {claim_id}'
     payroll_period: string
   }
-> gmail.send { to: employee_email, template: 'claim_approved' }

// On rejection
rejection_payload {
  claim_id: string,
  rejected_by_slack_id: string,
  rejection_reason: string,
  rejection_timestamp: ISO8601
}
-> slack.notify { channel: finance_admin_slack_id, message: rejection_summary }
-> gmail.send { to: employee_email, template: 'claim_rejected', reason: rejection_reason }

// ─── TRIGGER ────────────────────────────────────────────────────────────────
// Employee submits expense claim via Expensify
expensify.webhook -> automation_platform.receive {
  claim_id: 'EXP-{YYYYMMDD}-{seq}',
  employee_email: string,
  submission_timestamp: ISO8601,
  amount: float,
  currency: string,
  merchant_name: string,
  merchant_category: string,  // Expensify-assigned category
  receipt_url: string | null,
  description: string
}

// ─── DEDUPLICATE ─────────────────────────────────────────────────────────────
IF claim_id EXISTS IN processed_claims_log -> HALT (suppress duplicate)
ELSE -> CONTINUE, write claim_id to processed_claims_log

// ─── AGENT 1: Receipt Extraction and Policy Agent ────────────────────────────
// Step A: Download and store receipt
GET expensify.receipt_url
  -> store to Google Drive: /ExpenseReceipts/{YYYY-MM}/{claim_id}.{ext}
  -> receipt_gdrive_url: string

// Step B: OCR extraction
ocr_engine.extract(receipt_gdrive_url) -> {
  ocr_amount: float,
  ocr_date: ISO8601,
  ocr_merchant: string,
  ocr_confidence: float       // 0.0 - 1.0
}

// Step C: Confidence gate
IF ocr_confidence < 0.85
  -> route to finance_admin (manual review), HALT agent pipeline

// Step D: Policy check
policy_engine.evaluate {
  amount: ocr_amount,
  merchant_category: merchant_category,
  receipt_present: receipt_url != null,
  policy_rules: config.expense_policy_rules
} -> {
  policy_verdict: 'pass' | 'fail',
  flag_reason_code: string | null,
  flag_reason_human: string | null
}

// Step E: Fail path - send receipt chase via Gmail
IF policy_verdict == 'fail'
  -> gmail.send {
       to: employee_email,
       template: 'receipt_chase',
       reason: flag_reason_human,
       reply_to: 'expenses-intake@[YourCompany.com]',
       attempt_number: int  // max 3, interval 48h
     }
  -> write chase_log { claim_id, attempt_number, chase_timestamp }
  -> HALT (await resubmission)

// Step F: Pass path - emit verified_claim
IF policy_verdict == 'pass'
  -> verified_claim {
       claim_id, employee_email, amount_usd: ocr_amount,
       merchant_name: ocr_merchant, merchant_category,
       receipt_gdrive_url, policy_verdict: 'pass',
       extracted_date: ocr_date
     }

// ─── AGENT 2: GL Coding and Xero Sync Agent ─────────────────────────────────
// Step G: GL mapping lookup
gl_mapping_table.lookup(merchant_category) -> {
  xero_account_code: string,
  xero_account_name: string,
  tax_type: string
}

IF no match found
  -> route to finance_admin (unmapped category), log unmapped_category_event, HALT

// Step H: Create Xero draft spend money record
xero.createSpendMoneyTransaction {
  status: 'DRAFT',
  contact_name: expensify.employee_full_name,
  date: extracted_date,
  amount: amount_usd,
  account_code: xero_account_code,
  description: description,
  reference: claim_id,
  tax_type: tax_type
} -> xero_transaction_id: string

// Step I: Attach receipt to Xero record
xero.files.upload {
  transaction_id: xero_transaction_id,
  file_url: receipt_gdrive_url,
  filename: '{claim_id}_receipt.{ext}'
}

// Step J: Emit xero_draft_record
xero_draft_record {
  xero_transaction_id, claim_id,
  contact_name, employee_email,
  date: extracted_date, amount: amount_usd,
  account_code: xero_account_code,
  account_name: xero_account_name,
  description, receipt_attachment_url: receipt_gdrive_url
}

// ─── AGENT 3: Approval Routing and Notification Agent ───────────────────────
// Step K: Manager lookup
manager_matrix.lookup(employee_email) -> {
  manager_slack_id: string,
  manager_email: string
}

// Step L: Send Slack approval request
slack.postMessage {
  channel: manager_slack_id,
  blocks: [
    { type: 'section', text: 'Expense claim pending approval' },
    { type: 'fields', fields: [amount, merchant_name, account_name, date] },
    { type: 'actions', elements: [
        { action_id: 'approve_claim', text: 'Approve' },
        { action_id: 'reject_claim',  text: 'Reject'  }
      ]
    }
  ],
  metadata: { claim_id, xero_transaction_id }
} -> slack_message_ts: string

// Step M: 24-hour reminder (scheduled)
IF no action after 24h
  -> slack.postMessage (thread_ts: slack_message_ts) { text: 'Reminder: claim awaiting approval' }
IF no action after 48h
  -> slack.postMessage { channel: finance_admin_slack_id, text: 'Escalation: claim {claim_id} unanswered' }

// Step N: Approval path
ON slack.action(action_id: 'approve_claim') -> {
  approved_by_slack_id, approval_timestamp
}
  -> xero.updateTransaction { id: xero_transaction_id, status: 'AUTHORISED' }
  -> gusto.addReimbursementLine {
       employee_id: gusto.lookupByEmail(employee_email),
       amount: amount_usd,
       description: 'Expense reimbursement: {claim_id}',
       payroll_period: gusto.currentOpenPeriod
     }
  -> gmail.send { to: employee_email, template: 'claim_approved',
       vars: { amount: amount_usd, payroll_date: gusto.nextPayrollDate } }
  -> write approval_log { claim_id, xero_transaction_id, approved_by_slack_id, approval_timestamp }

// Step O: Rejection path
ON slack.action(action_id: 'reject_claim') -> {
  rejected_by_slack_id, rejection_reason, rejection_timestamp
}
  -> slack.postMessage { channel: finance_admin_slack_id,
       text: 'Claim {claim_id} rejected: {rejection_reason}' }
  -> gmail.send { to: employee_email, template: 'claim_rejected',
       vars: { reason: rejection_reason } }
  -> write rejection_log { claim_id, rejected_by_slack_id, rejection_reason, rejection_timestamp }

// ─── END OF PIPELINE ─────────────────────────────────────────────────────────