Developer Handover Pack

Developer Handover Pack

New Tool Evaluation & Rollout

Receives the structured intake form submission, creates a Jira ticket with all captured request fields, queries the Notion software register for duplicate or overlapping tools, flags any match on the Jira ticket, and posts an acknowledgement message to the requestor in Slack. This agent eliminates the unstructured multi-channel request intake and the informal manual duplicate check. All intake data is normalised at this stage and carried forward as the canonical record for the evaluation.

// Input
form.requestor_name        : string
form.requestor_email       : string
form.tool_name             : string
form.use_case              : string
form.user_count            : integer
form.budget_range          : string
form.integrations_needed   : string[]
form.submitted_at          : ISO8601 timestamp

// Output
jira.ticket_id             : string   // e.g. IT-204
jira.ticket_status         : string   // 'Intake Received'
jira.duplicate_flag        : boolean  // true if Notion match found
jira.duplicate_tool_name   : string   // populated if duplicate_flag = true
slack.ack_message_ts       : string   // Slack message timestamp for threading

Triggered when the Jira ticket status transitions to 'Evaluation In Progress', this agent generates a pre-built security checklist and a standardised evaluation scorecard in Notion, both pre-populated with the request details from the Jira ticket. It monitors Notion for checklist and scorecard completion, then sends a formatted approval request email via Google Workspace to the designated approver. If no response is recorded within 48 hours, a follow-up reminder is queued automatically. The agent continues queuing reminders until a decision is recorded in Jira, at which point it closes the approval loop.

// Input
jira.ticket_id             : string
jira.tool_name             : string
jira.requestor_name        : string
jira.requestor_email       : string
jira.use_case              : string
jira.user_count            : integer
jira.budget_range          : string
jira.integrations_needed   : string[]

// Output (on scorecard + checklist creation)
notion.security_checklist_page_id  : string
notion.scorecard_page_id           : string
notion.checklist_status            : string   // 'Pending' | 'Complete'
notion.scorecard_status            : string   // 'Pending' | 'Complete'

// Output (on approval request sent)
gmail.approval_email_message_id    : string
gmail.reminder_scheduled_at        : ISO8601 timestamp
jira.ticket_status                 : string   // 'Pending Approval'

// On approval
jira.approval_decision             : string   // 'Approved' | 'Rejected'
jira.decision_recorded_at          : ISO8601 timestamp
jira.approver_name                 : string
jira.ticket_status                 : string   // 'Approved' | 'Rejected'

Triggered when the Jira ticket status transitions to 'Approved', this agent sends a DocuSign envelope containing the vendor agreement or internal purchase order to the required signatories. Once the envelope is completed, the agent updates the Notion software register with the new tool entry including licence count, renewal date, owner, and monthly cost. It then sends a Slack notification to the requestor and any named users confirming the tool is live and linking to onboarding materials. If the approval decision is 'Rejected', the agent records the outcome in Jira and notifies the requestor via Slack without triggering DocuSign.

// Input
jira.ticket_id             : string
jira.approval_decision     : string   // 'Approved' | 'Rejected'
jira.tool_name             : string
jira.requestor_name        : string
jira.requestor_email       : string
jira.user_count            : integer
jira.budget_range          : string
jira.approver_name         : string
jira.decision_recorded_at  : ISO8601 timestamp

// On approval: DocuSign output
docusign.envelope_id       : string
docusign.envelope_status   : string   // 'sent' | 'completed' | 'declined'
docusign.signed_at         : ISO8601 timestamp

// On signature completed: Notion output
notion.register_page_id    : string   // new entry in Software Register
notion.tool_name           : string
notion.licence_count       : integer
notion.renewal_date        : date
notion.owner               : string
notion.monthly_cost_usd    : number
notion.status              : string   // 'Active'

// Output: Slack notification
slack.rollout_message_ts   : string
slack.channel_or_user      : string

// ============================================================
// TRIGGER
// ============================================================
// Event: Google Workspace intake form submitted
// Webhook payload received by orchestration layer

TRIGGER {
  form.requestor_name        = 'string'
  form.requestor_email       = 'string'
  form.tool_name             = 'string'
  form.use_case              = 'string'
  form.user_count            = integer
  form.budget_range          = 'string'
  form.integrations_needed   = ['string', ...]
  form.submitted_at          = ISO8601
}

// ============================================================
// AGENT 1: Request Intake Agent
// ============================================================

// Step 1a: Create Jira ticket
POST /rest/api/3/issue {
  project.key   -> env: JIRA_PROJECT_KEY
  issuetype     -> 'Task' or 'Tool Request'
  summary       -> form.tool_name + ' - Tool Request'
  description   -> form.use_case
  customfield_requestor_name   -> form.requestor_name
  customfield_requestor_email  -> form.requestor_email
  customfield_user_count       -> form.user_count
  customfield_budget_range     -> form.budget_range
  customfield_integrations     -> form.integrations_needed
  status        -> 'Intake Received'
}
RETURNS: jira.ticket_id  // e.g. 'IT-204'

// Step 1b: Query Notion software register for duplicate
POST /v1/databases/{NOTION_SOFTWARE_REGISTER_DB_ID}/query {
  filter: { property: 'Tool Name', rich_text: { contains: form.tool_name } }
}
IF results.length > 0:
  jira.duplicate_flag      = true
  jira.duplicate_tool_name = results[0].properties['Tool Name'].title
  // Update Jira ticket with duplicate flag; halt agent handoff
  // IT Manager reviews and closes ticket manually
ELSE:
  jira.duplicate_flag = false
  // Proceed to agent handoff

// Step 1c: Acknowledge requestor via Slack
GET /api/users.lookupByEmail?email={form.requestor_email}
  -> slack.user_id  (fallback: post to #it-requests if not found)
POST /api/chat.postMessage {
  channel -> slack.user_id
  text    -> 'Your request for {form.tool_name} has been received. Ticket: {jira.ticket_id}'
}
RETURNS: slack.ack_message_ts

// ============================================================
// AGENT 1 -> AGENT 2 HANDOFF
// Condition: jira.duplicate_flag = false
// Trigger: Jira ticket status updated to 'Evaluation In Progress'
// ============================================================

// ============================================================
// AGENT 2: Evaluation and Approval Agent
// ============================================================

// Step 2a: Duplicate Notion security checklist template
POST /v1/pages {
  parent.database_id -> env: NOTION_SECURITY_CHECKLIST_DB_ID
  properties: {
    'Tool Name'    -> jira.tool_name
    'Ticket ID'    -> jira.ticket_id
    'Status'       -> 'Pending'
    'Assigned To'  -> 'IT Manager'
  }
  // Content cloned from NOTION_SECURITY_CHECKLIST_TEMPLATE_ID
}
RETURNS: notion.security_checklist_page_id

// Step 2b: Duplicate Notion scorecard template
POST /v1/pages {
  parent.database_id -> env: NOTION_SCORECARD_DB_ID
  properties: {
    'Tool Name'        -> jira.tool_name
    'Ticket ID'        -> jira.ticket_id
    'Use Case'         -> jira.use_case
    'User Count'       -> jira.user_count
    'Budget Range'     -> jira.budget_range
    'Integrations'     -> jira.integrations_needed
    'Scorecard Status' -> 'Pending'
  }
}
RETURNS: notion.scorecard_page_id

// Step 2c: Poll Notion for checklist and scorecard completion
// Scheduled check every 6 hours
GET /v1/pages/{notion.security_checklist_page_id}
  -> notion.checklist_status  // watch for 'Complete'
GET /v1/pages/{notion.scorecard_page_id}
  -> notion.scorecard_status  // watch for 'Complete'

// Step 2d: Send approval request email once both statuses = 'Complete'
POST /gmail/v1/users/me/messages/send {
  to      -> approver_email  // resolved from APPROVER_EMAIL env var
  subject -> 'Approval required: {jira.tool_name} evaluation'
  body    -> evaluation summary + notion.scorecard_page_id URL
}
RETURNS: gmail.approval_email_message_id
SET: gmail.reminder_scheduled_at = now() + 48h
UPDATE: jira.ticket_status -> 'Pending Approval'

// Step 2e: Reminder logic (scheduled poller every 24h)
IF jira.ticket_status = 'Pending Approval'
   AND now() > gmail.reminder_scheduled_at:
  // Send reminder email (up to 3 times)
  // On 3rd miss: POST Slack alert to #it-alerts

// Step 2f: Capture approval decision
// Via Jira ticket status update (manual by approver or form response)
ON jira.ticket_status IN ('Approved', 'Rejected'):
  jira.approval_decision    = ticket.status
  jira.decision_recorded_at = now()
  jira.approver_name        = ticket.updated_by.displayName

// ============================================================
// AGENT 2 -> AGENT 3 HANDOFF
// Trigger: Jira ticket status transitions to 'Approved' or 'Rejected'
// ============================================================

// ============================================================
// AGENT 3: Procurement and Rollout Agent
// ============================================================

// Branch A: Approval decision = 'Rejected'
IF jira.approval_decision = 'Rejected':
  UPDATE jira.ticket_status -> 'Rejected'
  POST /api/chat.postMessage to requestor slack.user_id
    text -> 'Your request for {jira.tool_name} was not approved.'
  HALT

// Branch B: Approval decision = 'Approved'
// Step 3a: Send DocuSign envelope
POST /v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes {
  templateId        -> env: DOCUSIGN_TEMPLATE_ID
  templateRoles: [
    { roleName: 'IT Manager',       email: IT_MANAGER_EMAIL, name: IT_MANAGER_NAME }
    { roleName: 'Finance Controller', email: FINANCE_EMAIL,  name: FINANCE_NAME }
  ]
  status: 'sent'
}
RETURNS: docusign.envelope_id

// Step 3b: Listen for DocuSign envelope webhook event
ON docusign.envelope_status = 'completed':
  docusign.signed_at = envelope.completedDateTime

  // Step 3c: Update Notion software register
  POST /v1/pages {
    parent.database_id -> env: NOTION_SOFTWARE_REGISTER_DB_ID
    properties: {
      'Tool Name'      -> jira.tool_name
      'Status'         -> 'Active'
      'Licence Count'  -> jira.user_count
      'Owner'          -> jira.requestor_name
      'Monthly Cost'   -> parsed from jira.budget_range
      'Renewal Date'   -> signed_at + 12 months
      'Ticket ID'      -> jira.ticket_id
    }
  }
  RETURNS: notion.register_page_id

  // Step 3d: Send Slack rollout notification
  POST /api/chat.postMessage {
    channel -> slack.user_id (requestor)
    text    -> '{jira.tool_name} is approved and being provisioned.
                Onboarding materials: {notion.scorecard_page_id URL}'
  }
  RETURNS: slack.rollout_message_ts

ON docusign.envelope_status = 'declined':
  UPDATE jira.ticket_status -> 'Procurement Stalled'
  POST Slack alert to IT Manager DM
  HALT

// ============================================================
// END OF FLOW
// ============================================================