Cookbooks

Mirroring Approvals

View as Markdown

Objective

This cookbook describes how to mirror approvals from other business systems into your AI assistant. You can use this cookbook to recreate the experience that your users have with our built-in approval mirroring experience.

This specifically ensures that your users get the full experience of our Approval Queue (i.e. ability to ask “which approvals do I still need to complete”).

Architecture

At a high-level, there are going to be two plugins needed in order to build this experience.

  1. Polling Plugin. Periodically checks for new records that need approval from the user
  2. Notification Plugin. Sends the target user a notification, validates the status of the record on response, and pushes the update to the system of record.

Polling Plugin

  • Trigger: Scheduled job. Runs on an interval.
  • Body: Compound action. Fetches notifications that are eligible for notification.
1steps:
2  - action:
3      action_name: get_pending_approvals_from_system
4      output_key: pending_approvals
5      input_args:
6				# Everything created in the last 10 minutes, assuming the job runs every 10 min.
7        created_after_timestamp: '$TIME() - 600'
8  - for:
9      each: approval
10      index: idx
11      in: data.pending_approvals.records
12      output_key: webhook_results
13      steps:
14        - action:
15            action_name: send_webhook
16            input_args:
17              payload: approval

Notification Plugin

  • Trigger Webhook. Triggered by the polling plugin.

    For this cookbook, assume the payload looks something like this:

    1{
    2  "report_id": "EXP-2025-09-15-001",
    3  "total_amount": 750.50,
    4  "currency": "USD",
    5  "description": "Client dinner and travel for Q3 sales meeting.",
    6  "submitter": {
    7    "email_addr": "jane.doe@example.com",
    8    "full_name": "Jane Doe",
    9    "record_id": "user_12345"
    10  },
    11  "approver": {
    12    "email_addr": "john.smith@example.com",
    13    "full_name": "John Smith",
    14    "record_id": "user_67890"
    15  },
    16  "line_items": [
    17    {
    18      "item": "Client Dinner at The Grand Restaurant",
    19      "category": "Meals & Entertainment",
    20      "amount": 250.00
    21    },
    22    {
    23      "item": "Round-trip flight to NYC",
    24      "category": "Travel",
    25      "amount": 450.50
    26    },
    27    {
    28      "item": "Taxi from JFK to Hotel",
    29      "category": "Travel",
    30      "amount": 50.00
    31    }
    32  ]
    33}

  • Body: Compound action. Notifies the user and processes their response.

1steps:
2  # Step 1: Fetch full User objects for both submitter and approver in a single call.
3  - action:
4      action_name: mw.batch_get_users_by_email
5      output_key: user_data
6      input_args:
7        user_emails:
8          - data.payload.submitter_email
9          - data.payload.approver_email
10
11  # Step 2: Create the generic approval request with formatted details.
12  - action:
13      action_name: mw.create_generic_approval_request
14      output_key: approval_request_result
15      input_args:
16        approvers: 'data.user_data.user_records.$FILTER(u => u.user.email_addr == data.payload.approver_email)'
17        users_requested_for: 'data.user_data.user_records.$FILTER(u => u.user.email_addr == data.payload.submitter_email)'
18        approval_details:
19          RENDER():
20            template: |
21              <p><b>Expense Report from {{submitter_name}}</b></p>
22              <p><b>Total:</b> ${{total_amount}} {{currency}}</p>
23              <p><b>Description:</b> {{description}}</p>
24              <p><b>Line Items:</b></p>
25              {{{line_items_html}}}
26            args:
27              submitter_name: 'data.user_data.user_records.$FILTER(u => u.user.email_addr == data.payload.submitter_email)[0].user.full_name'
28              total_amount: data.payload.total_amount
29              currency: data.payload.currency
30              description: data.payload.description
31              line_items_html:
32                CONCAT():
33                  items:
34                    - '"<ul>"'
35                    - MAP():
36                        items: data.payload.line_items
37                        converter:
38                          RENDER():
39                            template: '<li><b>{{item}}</b> ({{category}}): ${{amount}}</li>'
40                            args:
41                              item: item.item
42                              category: item.category
43                              amount: item.amount
44                    - '"</ul>"'
45                  separator: ''
46  # Step 3: Switch on the approval status to update the system of record.
47  - switch:
48      cases:
49        - condition: 'data.approval_request_result.status == "APPROVED"'
50          steps:
51            - action:
52                action_name: update_expense_report_in_sor
53                output_key: sor_update_result
54                input_args:
55                  report_id: data.payload.report_id
56                  status: '"approved"'
57        - condition: 'data.approval_request_result.status == "DENIED"'
58          steps:
59            - action:
60                action_name: update_expense_report_in_sor
61                output_key: sor_update_result
62                input_args:
63                  report_id: data.payload.report_id
64                  status: '"denied"'

Risks

  • Rate Limits. Approvals tend to be bursty, so we recommend building rate limit checks into your plugin.

    • Make sure you secure your webhooks! Unauthenticated webhooks have low rate limits, so they won’t be able to process all of the events you are generating.
    • Throttle your polling plugin. You can use a delay config to space your webhook events out.

  • Stale Approvals. After you send your approval request, it can go “stale.” For example, the user might log into the application and approve it there, but the approval request will still be in the assistant. Or another approver might handle the request, making the user’s response irrelevant.

    We recommend validating the approval is still “fresh” before taking action. However, there is currently no way to remove it from their “queue” of approvals.

  • Duplicate notifications. To avoid notifying the same user twice about the same approval, you should implement some sort of deduplication logic in your compound action. We recommend that you…

    1. Use time-based cursors. That way you’ll only fetch the approval once (e.g. by the created_on date)
    2. Use worknotes & audit trails. You can leave a comment on the approval object (a purchase requisition, expense report, etc.) to log whether or not you’ve already reached out to the user. Then, in your notification plugin, check for that marker before creating the approval request.

  • Approval requests will expire after 30 days. Generally users don’t act on requests that are over 30 days old. So if your approval request expires, we recommend escalating to a different owner rather than just notifying the same user again.