Integration and API Spec

Integration and API Spec

Purchase Approval Workflow

Source trigger for the entire workflow. A form submission fires a webhook to the orchestration layer, delivering the structured request payload. The orchestration layer does not poll Jotform; it listens for inbound webhook POST requests only.

// Inbound webhook payload (abridged)
{
  "formID": "<JOTFORM_FORM_ID>",
  "submissionID": "<unique_submission_id>",
  "rawRequest": {
    "q1_requesterName": "Jane Smith",
    "q2_requesterEmail": "jane.smith@yourcompany.com",
    "q3_department": "Marketing",
    "q4_supplierName": "Acme Supplies Ltd",
    "q5_amountUsd": "1200.00",
    "q6_businessJustification": "Event collateral for Q3 conference",
    "q7_supportingDocument": "https://www.jotform.com/uploads/.../quote.pdf"
  }
}

Serves two roles: (1) the master purchase register where every request is logged with a unique request ID, timestamps, and approval status; (2) the spend-threshold rules table that the Approval Routing Agent reads to determine the correct approver. Both live in the same Google Sheets workbook in separate named sheets.

// Write to PurchaseRegister on new Jotform submission
sheets.spreadsheets.values.append(
  spreadsheetId: GOOGLE_SHEETS_WORKBOOK_ID,
  range: 'PurchaseRegister!A:P',
  valueInputOption: 'USER_ENTERED',
  body: { values: [[
    request_id, submitted_at, requester_name, requester_email,
    department, supplier_name, amount_usd, business_justification,
    document_url, 'Pending', '', '', '', '', ''
  ]] }
)

// Read ApproverRules for threshold lookup
sheets.spreadsheets.values.get(
  spreadsheetId: GOOGLE_SHEETS_WORKBOOK_ID,
  range: 'ApproverRules!A:F'
)

Used by the Approval Routing Agent to deliver a structured Block Kit approval message to the identified approver. The approver clicks an inline Approve or Reject button; Slack posts the interaction payload back to the orchestration layer's interactivity endpoint.

// chat.postMessage payload
POST https://slack.com/api/chat.postMessage
Authorization: Bearer <SLACK_BOT_TOKEN>
{
  "channel": "<approver_slack_user_id>",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Purchase Request {{request_id}}*\n{{requester_name}} | {{department}}\nSupplier: {{supplier_name}}\nAmount: ${{amount_usd}}\nJustification: {{business_justification}}" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "Approve" },
        "style": "primary", "action_id": "<SLACK_APPROVE_ACTION_ID>", "value": "{{request_id}}" },
      { "type": "button", "text": { "type": "plain_text", "text": "Reject" },
        "style": "danger", "action_id": "<SLACK_REJECT_ACTION_ID>", "value": "{{request_id}}" }
    ] }
  ]
}

Used in three distinct scenarios: (1) Agent 1 sends a resubmission prompt when a Jotform submission has missing required fields; (2) Agent 2 sends a 48-hour escalation email to the approver and their line manager; (3) Agent 3 sends the outcome notification to the requester on approval or rejection.

// Gmail API send (escalation example)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer <service_account_access_token>
{
  "raw": "<base64url-encoded RFC 2822 message>",
  // Decoded headers:
  // From: finance-approvals@yourcompany.com  (GMAIL_SENDER_ADDRESS)
  // To: <approver_email>
  // CC: <line_manager_email>
  // Subject: Pending approval reminder: PR-0042 awaiting your decision
  // Content-Type: text/html; charset=utf-8
}

Used exclusively by the PO Creation and Notification Agent to create a draft purchase order on approval of a purchase request. The draft PO is not sent to the supplier by the automation; it requires a finance manager to review and confirm it in the Xero UI before dispatch.

// POST /api.xro/2.0/PurchaseOrders
PUT https://api.xero.com/api.xro/2.0/PurchaseOrders
Authorization: Bearer <XERO_ACCESS_TOKEN>
Xero-Tenant-Id: <XERO_TENANT_ID>
Content-Type: application/json
{
  "PurchaseOrders": [{
    "Contact": { "Name": "{{supplier_name}}" },
    "Date": "{{today_iso8601}}",
    "DeliveryDate": null,
    "Status": "DRAFT",
    "Reference": "{{request_id}}",
    "LineItems": [{
      "Description": "{{business_justification}}",
      "Quantity": 1.0,
      "UnitAmount": {{amount_usd}},
      "AccountCode": "<XERO_DEFAULT_ACCOUNT_CODE>"
    }]
  }]
}

// Expected response field
response.PurchaseOrders[0].PurchaseOrderNumber -> stored as po_number

// Credential store contents (production keys)
// All values are secrets; shown here as key names only

JOTFORM_API_KEY                  // Jotform account API key
JOTFORM_FORM_ID                  // Form ID of the purchase request form
JOTFORM_WEBHOOK_SECRET           // HMAC-SHA256 shared secret for signature validation

GOOGLE_SERVICE_ACCOUNT_JSON      // Full service account JSON key (base64 encoded)
GOOGLE_SHEETS_WORKBOOK_ID        // Workbook ID from the Google Sheets URL

SLACK_BOT_TOKEN                  // Bot token (xoxb-...) for chat.postMessage and users.lookupByEmail
SLACK_SIGNING_SECRET             // Signing secret for interaction payload validation
SLACK_APPROVE_ACTION_ID          // Action ID string for the Approve button
SLACK_REJECT_ACTION_ID           // Action ID string for the Reject button

GMAIL_SENDER_ADDRESS             // From address, e.g. finance-approvals@yourcompany.com
GMAIL_TEMPLATE_RESUBMIT          // Template ID or inline template for resubmission prompt
GMAIL_TEMPLATE_ESCALATION        // Template ID or inline template for escalation email
GMAIL_TEMPLATE_OUTCOME           // Template ID or inline template for outcome notification

XERO_CLIENT_ID                   // Xero app client ID
XERO_CLIENT_SECRET               // Xero app client secret
XERO_ACCESS_TOKEN                // Short-lived access token (auto-refreshed, 30 min TTL)
XERO_REFRESH_TOKEN               // Long-lived refresh token for token renewal
XERO_TENANT_ID                   // Organisation (tenant) ID from Xero connections endpoint
XERO_DEFAULT_ACCOUNT_CODE        // Default account code for PO line items (e.g. '500')

ADMIN_ALERT_EMAIL                // Email address to receive workflow error alerts