Developer Handover Pack

Developer Handover Pack

Supplier Onboarding Automation

Handles all initial supplier outreach and timed follow-up without any manual involvement. When a new approved supplier record is detected in the connected source (Google Form trigger, CRM entry, or spreadsheet row), this agent sends a personalised intake form link via Gmail and monitors for submission. If no submission is detected after 48 hours, a first reminder is dispatched automatically. A second reminder fires at 96 hours if the form remains incomplete. The agent's sole output is a confirmed, fully completed intake form submission that downstream agents can act on.

// Input
supplier_name: string
supplier_email: string
approval_date: ISO8601 date
approved_by: string

// Output
form_submission_id: string          // Google Forms response ID
supplier_business_name: string
supplier_tax_id: string             // ABN or tax reference
supplier_bank_bsb: string
supplier_bank_account: string
supplier_primary_contact_name: string
supplier_primary_contact_email: string
supplier_primary_contact_phone: string
submission_timestamp: ISO8601 datetime
reminder_count: integer             // 0, 1, or 2

Fires when the intake form submission is confirmed and documents are attached or linked. This agent checks submitted documents against a configured required-items checklist (insurance certificate, signed NDA or trading terms, tax form). It detects missing items and checks expiry dates on date-stamped documents where parseable. When all required items are present and valid, the agent posts a structured Slack notification to the finance lead summarising the supplier, listing each document with its status, and providing a direct approval or rejection action link. When items are missing or expired, the agent routes a gap report to the finance lead and triggers a re-request email to the supplier via Gmail. The agent does not assess the legal sufficiency of document content.

// Input
form_submission_id: string
supplier_name: string
supplier_email: string
supplier_tax_id: string
documents_received: array<{doc_type: string, file_url: string, expiry_date: date|null}>

// Output (all-docs-complete path)
document_review_status: 'complete' | 'incomplete'
completeness_report: array<{doc_type: string, status: 'present'|'missing'|'expired', expiry_date: date|null}>
slack_notification_ts: string       // Slack message timestamp for threading
docusign_envelope_id: string        // Created and sent on complete path
docusign_envelope_status: string    // 'sent'

// Output (gap-detected path)
document_review_status: 'incomplete'
gap_report: array<{doc_type: string, reason: 'missing'|'expired'}>
supplier_gap_email_sent: boolean
finance_alert_sent: boolean

// On approval (received from Supplier Activation Agent trigger)
docusign_envelope_signed_timestamp: ISO8601 datetime
docusign_completed_envelope_id: string

Fires when the finance lead confirms compliance approval via the Slack interactive action or the connected approval step. This agent creates the supplier record in Xero (including bank account, payment terms, and tax information sourced directly from the intake form output), creates a matching contact record in HubSpot tagged as an active supplier, and posts a final Slack confirmation to the operations channel listing the supplier name, Xero contact ID, and activation date. This agent is the terminal step of the automated flow and its outputs are the source of truth for downstream procurement and accounts-payable processes.

// Input
supplier_name: string
supplier_email: string
supplier_tax_id: string
supplier_bank_bsb: string
supplier_bank_account: string
supplier_primary_contact_name: string
supplier_primary_contact_phone: string
docusign_completed_envelope_id: string
approval_confirmed_by: string       // Slack user ID of finance lead
approval_timestamp: ISO8601 datetime

// Output
xero_contact_id: string             // Created Xero contact record ID
hubspot_contact_id: string          // Created HubSpot contact record ID
slack_activation_message_ts: string // Posted to operations channel
activation_date: ISO8601 date

// ─────────────────────────────────────────────────────────────────
// TRIGGER: New approved supplier record detected
// Source: Google Sheet row | HubSpot deal stage | spreadsheet entry
// ─────────────────────────────────────────────────────────────────
trigger.supplier_name          -> workflow.context.supplier_name
trigger.supplier_email         -> workflow.context.supplier_email
trigger.approval_date          -> workflow.context.approval_date
trigger.approved_by            -> workflow.context.approved_by

// ─────────────────────────────────────────────────────────────────
// AGENT 1: Intake and Chaser Agent
// ─────────────────────────────────────────────────────────────────

// Deduplication check
Google_Forms.response_sheet.lookup(supplier_email)
  -> IF existing_submission_age < 7_days: SKIP send, forward existing
  -> ELSE: proceed

// Initial outreach
Gmail.send({
  to:      workflow.context.supplier_email,
  subject: 'Action required: Complete your supplier onboarding form',
  body:    template_intake_email(supplier_name, form_url),
})
  -> gmail.message_id            -> workflow.context.initial_email_id
  -> send_timestamp              -> workflow.context.intake_email_sent_at

// Reminder logic (48h + 96h from intake_email_sent_at)
IF Google_Forms.response_sheet.poll() == no_submission AND elapsed >= 48h:
  Gmail.send(template_reminder_1)  -> workflow.context.reminder_1_sent_at
IF Google_Forms.response_sheet.poll() == no_submission AND elapsed >= 96h:
  Gmail.send(template_reminder_2)  -> workflow.context.reminder_2_sent_at
  workflow.context.reminder_count  = 2

// Form submission detected
Google_Forms.response_sheet.on_new_row:
  form_submission_id             -> workflow.context.form_submission_id
  supplier_business_name         -> workflow.context.supplier_business_name
  supplier_tax_id                -> workflow.context.supplier_tax_id
  supplier_bank_bsb              -> workflow.context.supplier_bank_bsb
  supplier_bank_account          -> workflow.context.supplier_bank_account
  supplier_primary_contact_name  -> workflow.context.supplier_primary_contact_name
  supplier_primary_contact_email -> workflow.context.supplier_primary_contact_email
  supplier_primary_contact_phone -> workflow.context.supplier_primary_contact_phone
  submission_timestamp           -> workflow.context.submission_timestamp

// ── HANDOFF: Intake and Chaser Agent -> Document Review Agent ────
// Payload: form_submission_id, supplier_name, supplier_email,
//          supplier_tax_id, submission_timestamp
// ─────────────────────────────────────────────────────────────────

// ─────────────────────────────────────────────────────────────────
// AGENT 2: Document Review Agent
// ─────────────────────────────────────────────────────────────────

// Document completeness check
checklist = ['insurance_certificate', 'nda_or_trading_terms', 'tax_form']
documents_received[]           -> check_each_against(checklist)
  doc.doc_type                 -> match to checklist item
  doc.expiry_date              -> compare to today() IF not null
  -> completeness_report[]     -> {doc_type, status, expiry_date}

// Branch: all docs complete and valid
IF document_review_status == 'complete':

  // Send DocuSign trading agreement
  DocuSign.Envelopes.create({
    templateId:    env.DOCUSIGN_TEMPLATE_ID,
    signerEmail:   workflow.context.supplier_email,
    signerName:    workflow.context.supplier_primary_contact_name,
    fields: {
      supplier_name:   workflow.context.supplier_business_name,
      supplier_tax_id: workflow.context.supplier_tax_id,
    }
  })
    -> docusign_envelope_id     -> workflow.context.docusign_envelope_id
    -> envelope_status          -> 'sent'

  // Notify finance lead via Slack
  Slack.chat.postMessage({
    channel: env.SLACK_FINANCE_LEAD_USER_ID,
    blocks:  template_compliance_review_block(
               supplier_name, completeness_report, docusign_envelope_id
             ),
    actions: ['approve', 'flag_gaps']
  })
    -> slack_notification_ts    -> workflow.context.slack_notification_ts

// Branch: gaps detected
IF document_review_status == 'incomplete':
  Gmail.send(template_gap_request_email(supplier_email, gap_report))
  Slack.chat.postMessage(template_gap_alert(finance_lead, gap_report))
    -> finance_alert_sent = true

// DocuSign signed event received (webhook callback)
DocuSign.Connect.webhook.on_envelope_completed:
  docusign_completed_envelope_id -> workflow.context.docusign_completed_envelope_id
  signed_timestamp               -> workflow.context.docusign_signed_at

// ── HANDOFF: Document Review Agent -> Supplier Activation Agent ──
// Trigger: Slack approval action OR DocuSign envelope completed
// Payload: supplier_name, supplier_email, supplier_tax_id,
//          supplier_bank_bsb, supplier_bank_account,
//          supplier_primary_contact_name, supplier_primary_contact_phone,
//          docusign_completed_envelope_id, approval_confirmed_by,
//          approval_timestamp
// ─────────────────────────────────────────────────────────────────

// ────────────────────────────────────────────────────────────��────
// AGENT 3: Supplier Activation Agent
// ─────────────────────────────────────────────────────────────────

// Xero deduplication
Xero.Contacts.get({ where: 'TaxNumber=="' + supplier_tax_id + '"' })
  -> IF match found: log conflict, Slack alert, HALT
  -> ELSE: proceed

// Create Xero supplier contact
Xero.Contacts.create({
  Name:            workflow.context.supplier_business_name,
  EmailAddress:    workflow.context.supplier_email,
  TaxNumber:       workflow.context.supplier_tax_id,
  BankAccountNumber: workflow.context.supplier_bank_account,
  BSBNumber:       workflow.context.supplier_bank_bsb,
  PaymentTerms:    env.DEFAULT_PAYMENT_TERMS,
  IsSupplier:      true
})
  -> xero_contact_id            -> workflow.context.xero_contact_id

// HubSpot deduplication
HubSpot.CRM.Contacts.search({ filterGroups: [{email: supplier_email}] })
  -> IF match found: update record, skip create
  -> ELSE: proceed

// Create HubSpot contact
HubSpot.CRM.Contacts.create({
  email:           workflow.context.supplier_email,
  firstname:       supplier_primary_contact_name.split(' ')[0],
  lastname:        supplier_primary_contact_name.split(' ')[1],
  phone:           workflow.context.supplier_primary_contact_phone,
  company:         workflow.context.supplier_business_name,
  supplier_status: 'active',
  lifecyclestage:  'other'
})
  -> hubspot_contact_id         -> workflow.context.hubspot_contact_id

// Post activation confirmation to Slack
Slack.chat.postMessage({
  channel: env.SLACK_OPS_CHANNEL_ID,
  blocks:  template_activation_block(
             supplier_name, xero_contact_id, hubspot_contact_id,
             activation_date, xero_record_url
           )
})
  -> slack_activation_message_ts -> workflow.context.slack_activation_message_ts

// ─────────────────────────────────────────────────────────────────
// TERMINAL: Supplier is active in Xero, HubSpot, and Slack confirmed
// ─────────────────────────────────────────────────────────────────