Integration and API Spec

Integration and API Spec

Project Milestone Tracking

Asana is the trigger source and the authoritative record for all milestone data. The orchestration layer polls the Asana API on a scheduled basis each morning at 08:00 and also listens for task update webhooks to capture owner status changes in near-real-time. All project IDs in scope must be stored in the credential store, not hardcoded in the workflow.

// Trigger payload (webhook, task due_on change)
{ "events": [{ "resource": { "gid": "<task_gid>", "resource_type": "task" }, "type": "changed", "change": { "field": "due_on", "new_value": "<YYYY-MM-DD>" }, "user": { "gid": "<user_gid>" } }] }

// Scheduled poll: GET /tasks/search
?workspace=<ASANA_WORKSPACE_GID>&due_on.before=<today>&completed=false&custom_fields.<MILESTONE_FIELD_GID>.is_set=true

// Task GET response fields used downstream
task.gid | task.name | task.due_on | task.assignee.gid | task.assignee.name | task.assignee.email | task.projects[0].name | task.permalink_url | task.completed

Google Sheets acts as the central milestone tracking log. The Milestone Monitor Agent writes overdue items to the sheet each morning; the Owner Reminder Agent reads from it to determine which items require escalation; and the Report Builder Agent reads the full sheet every Monday to generate the Notion status report. A fixed sheet schema must be in place before any agent connects.

// Write: Milestone Monitor Agent appends/updates a row
spreadsheets.values.batchUpdate -> range: 'MilestoneTracker!A:L'
values: [ task_gid, task_name, project_name, assignee_name, assignee_email, due_date, days_overdue, status, escalation_flag, last_reminder_sent, owner_response, last_updated_timestamp ]

// Read: Owner Reminder Agent reads escalation_flag column
spreadsheets.values.get -> range: 'MilestoneTracker!A:L' -> filter rows where I (escalation_flag) == 'YES'

// Read: Report Builder Agent reads full sheet every Monday
spreadsheets.values.get -> range: 'MilestoneTracker!A:L' -> group by C (project_name), H (status)

Gmail is used exclusively for outbound reminder emails sent by the Owner Reminder Agent to milestone task owners. Emails are personalised using a stored template with placeholders resolved at send time from the tracking sheet data. The automation sends on behalf of the authenticated Google account; the from address must be a recognised internal address to avoid spam filtering.

// Outbound: users.messages.send
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer <access_token>
{
  "raw": "<base64url-encoded RFC 2822 message>",
  // Resolved template fields injected before encoding:
  // To: {{assignee_email}}
  // From: {{GMAIL_SENDER_ADDRESS}}
  // Subject: 'Milestone overdue: {{task_name}} ({{days_overdue}} days)'
  // Body: resolved GMAIL_REMINDER_TEMPLATE_ID with all placeholders substituted
}

Slack is used by both the Owner Reminder Agent (escalation alerts to a project channel) and the Report Builder Agent (weekly digest to the leadership channel). Both use the Slack Web API via a Bot Token installed into the target workspace. Channel IDs must be stored in the credential store; channel names must never be hardcoded because they can be renamed without notice.

// Escalation alert: chat.postMessage
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {{SLACK_BOT_TOKEN}}
{
  "channel": "{{SLACK_ESCALATION_CHANNEL_ID}}",
  "text": "Escalation: *{{task_name}}* is {{days_overdue}} days overdue",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": ":red_circle: *{{task_name}}* — {{project_name}}\n*Owner:* <@{{stakeholder_slack_id}}>\n*Overdue by:* {{days_overdue}} days\n<{{asana_task_url}}|View in Asana>" } }
  ]
}

// Weekly digest: chat.postMessage to leadership channel
{
  "channel": "{{SLACK_LEADERSHIP_CHANNEL_ID}}",
  "text": "Weekly Milestone Report — {{report_date}}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn", "text": "*On track:* {{count_on_track}} | *At risk:* {{count_at_risk}} | *Overdue:* {{count_overdue}}\n<{{notion_report_url}}|View full report in Notion>" } }
  ]
}

Notion is the destination for the weekly milestone status report, written by the Report Builder Agent every Monday morning. The agent writes to a pre-created Notion database page, appending a dated child page for each weekly report. The parent database ID must be stored in the credential store. The Notion integration must be connected to the target workspace and granted access to the parent page.

// Create weekly report page
POST https://api.notion.com/v1/pages
Authorization: Bearer {{NOTION_API_KEY}}
Notion-Version: 2022-06-28
{
  "parent": { "database_id": "{{NOTION_PARENT_DATABASE_ID}}" },
  "properties": {
    "Title": { "title": [{ "text": { "content": "Milestone Status Report — Week of {{report_week_start_date}}" } }] },
    "Week": { "date": { "start": "{{report_week_start_date}}" } },
    "Status": { "select": { "name": "Published" } },
    "On Track Count": { "number": {{count_on_track}} },
    "At Risk Count": { "number": {{count_at_risk}} },
    "Overdue Count": { "number": {{count_overdue}} }
  }
}

// Append content blocks
POST https://api.notion.com/v1/blocks/{{new_page_id}}/children
// One toggle block per project, with milestone rows as bulleted list children

// Credential store manifest
// All entries stored in the orchestration platform's encrypted credential store
// Environment: PRODUCTION (duplicate all entries under SANDBOX prefix for test environment)

ASANA_CLIENT_ID                  = "<Asana OAuth app client ID>"
ASANA_CLIENT_SECRET              = "<Asana OAuth app client secret>"
ASANA_ACCESS_TOKEN               = "<OAuth access token — rotated automatically>"
ASANA_REFRESH_TOKEN              = "<OAuth refresh token — long-lived>"
ASANA_WORKSPACE_GID              = "<Asana workspace GID>"
ASANA_PROJECT_GIDS               = "<gid1>,<gid2>,<gid3>,..."  // comma-separated, all in-scope projects
ASANA_CUSTOM_FIELD_GID_MILESTONE = "<GID of milestone-type custom field>"
ASANA_WEBHOOK_SECRET             = "<HMAC-SHA256 secret provided by Asana on webhook registration>"

GOOGLE_OAUTH_CLIENT_ID           = "<Google Cloud project OAuth client ID>"
GOOGLE_OAUTH_CLIENT_SECRET       = "<Google Cloud project OAuth client secret>"
GOOGLE_OAUTH_ACCESS_TOKEN        = "<access token — expires 3600s, auto-refreshed>"
GOOGLE_OAUTH_REFRESH_TOKEN       = "<refresh token — long-lived>"

SHEETS_TRACKING_SPREADSHEET_ID   = "<Google Sheets document ID from URL>"
SHEETS_TRACKING_TAB_NAME         = "MilestoneTracker"
SHEETS_HEADER_ROW                = "1"

GMAIL_SENDER_ADDRESS             = "<authenticated sender email address>"
GMAIL_REPLY_TO_ADDRESS           = "<optional reply-to address>"
GMAIL_REMINDER_TEMPLATE_ID       = "reminder_v1"  // key into orchestration template store

SLACK_BOT_TOKEN                  = "xoxb-<workspace bot token>"
SLACK_ESCALATION_CHANNEL_ID      = "<channel ID — not channel name>"
SLACK_LEADERSHIP_CHANNEL_ID      = "<channel ID — not channel name>"
SLACK_FALLBACK_WEBHOOK_URL       = "https://hooks.slack.com/services/<path>"

NOTION_API_KEY                   = "secret_<Notion internal integration secret>"
NOTION_PARENT_DATABASE_ID        = "<Notion database page ID from URL>"

ESCALATION_THRESHOLD_DAYS        = "3"   // days overdue before escalation flag is set
ESCALATION_REMINDER_WAIT_HOURS   = "24"  // hours after first reminder before escalation fires
AGENT2_INBOUND_TRIGGER_URL       = "<orchestration platform internal webhook URL for Agent 2>"

// Note: rotate ASANA_ACCESS_TOKEN and GOOGLE_OAUTH_ACCESS_TOKEN automatically via OAuth refresh flow
// Note: ASANA_WEBHOOK_SECRET must be re-registered if the webhook is deleted and recreated