Integration and API Spec

Integration and API Spec

New Tool Evaluation and Rollout

Used by Agent 1 (Request Intake Agent) to create and label evaluation tickets, and by Agent 3 (Procurement and Rollout Agent) to record approval outcomes and rejections. The integration targets the Jira Cloud REST API v3.

// Input (Agent 1)
POST /rest/api/3/issue
{ projectKey, summary, description, customFields: { tool_name, requestor_email, use_case, user_count, budget_range, duplicate_flag } }

// Input (Agent 3 - rejection)
PUT /rest/api/3/issue/{issueKey}/transitions
{ transition: { id: REJECTED_TRANSITION_ID } }

// Output
{ id, key, self, fields: { status, cf[duplicate_flag], cf[tool_name] } }

Used by all three agents. Agent 1 queries the software register for duplicate detection. Agent 2 creates the security checklist page and evaluation scorecard page. Agent 3 appends the approved tool entry to the software register.

// Input (Agent 1 - duplicate check)
POST /v1/databases/{NOTION_SOFTWARE_REGISTER_DB_ID}/query
{ filter: { property: 'Tool Name', title: { contains: intake_tool_name } } }

// Input (Agent 2 - create checklist page)
POST /v1/pages
{ parent: { database_id: NOTION_CHECKLIST_DB_ID }, properties: { 'Tool Name': ..., 'Jira Ticket': ..., 'Assigned To': ... } }

// Input (Agent 3 - register update)
POST /v1/pages
{ parent: { database_id: NOTION_SOFTWARE_REGISTER_DB_ID }, properties: { 'Tool Name', 'Vendor', 'Monthly Cost', 'Licence Count', 'Renewal Date', 'Owner', 'Status': 'Active', 'Jira Ticket' } }

// Output
{ object: 'page', id: page_uuid, url: notion_page_url, properties: { ... } }

Used by Agent 2 (Evaluation and Approval Agent). Google Forms provides the structured intake trigger. Gmail sends the approval request email to the relevant manager and dispatches 48-hour reminder emails if no response is received.

// Input (form submission poll)
GET /v1/forms/{GOOGLE_FORM_ID}/responses
{ pageSize: 10, filter: 'timestamp > last_polled_at' }

// Input (send approval email)
POST /gmail/v1/users/me/messages/send
{ raw: base64_encoded_MIME_message }
  Subject: [ITEVAL] Tool Approval Request: {tool_name}
  Body: evaluation_summary_html + approve_link + reject_link

// Output
{ id: message_id, threadId, labelIds, snippet }

Used by Agent 3 (Procurement and Rollout Agent). Triggered when management approval is recorded in Jira. Creates and sends a DocuSign envelope from a pre-configured vendor agreement template to the required signatories. Completion status is polled to trigger the Notion register update.

// Input (create envelope from template)
POST /v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
{
  templateId: DOCUSIGN_TEMPLATE_ID,
  status: 'sent',
  templateRoles: [
    { roleName: DOCUSIGN_SIGNER_ROLE_VENDOR, name: vendor_contact_name, email: vendor_contact_email },
    { roleName: DOCUSIGN_SIGNER_ROLE_IT, name: it_manager_name, email: it_manager_email }
  ],
  emailSubject: 'Agreement for {tool_name} - Action Required',
  customFields: { textCustomFields: [ { name: 'tool_name', value: tool_name }, ... ] }
}

// Output (Connect webhook payload)
{ envelopeId, status: 'completed'|'declined'|'voided', completedDateTime, signers: [...] }

Used by Agent 1 (Request Intake Agent) to send an acknowledgement to the requestor on ticket creation, and by Agent 3 (Procurement and Rollout Agent) to send the rollout notification to the requestor and named users.

// Input (Agent 1 - acknowledgement DM)
POST /api/chat.postMessage
{ channel: requestor_slack_user_id, text: 'Your request for {tool_name} has been logged. Jira ticket: {jira_url}' }

// Input (Agent 3 - rollout notification)
POST /api/chat.postMessage
{
  channel: SLACK_ROLLOUT_CHANNEL_ID,
  blocks: [
    { type: 'section', text: '{tool_name} is approved and ready to use.' },
    { type: 'section', text: 'Onboarding docs: {ONBOARDING_DOCS_BASE_URL}/{tool_slug}' },
    { type: 'section', text: 'Software register: {notion_register_page_url}' }
  ]
}

// Output
{ ok: true, channel, ts, message: { text, bot_id } }

// CREDENTIAL STORE MANIFEST
// All values populated before workflow activation.
// Never hardcode any of these in workflow nodes.

// Jira
JIRA_API_TOKEN          = '<api-token-for-service-account>'
JIRA_SERVICE_EMAIL      = '<service-account-email>@yourdomain.com'
JIRA_BASE_URL           = 'https://<your-org>.atlassian.net'
JIRA_PROJECT_KEY        = 'ITEVAL'
JIRA_EVALUATION_BOARD_ID = '<numeric-board-id>'
JIRA_WEBHOOK_SECRET     = '<shared-secret-for-header-validation>'
JIRA_FIELD_TOOL_NAME    = 'cf[<custom-field-id>]'
JIRA_FIELD_REQUESTOR_EMAIL = 'cf[<custom-field-id>]'
JIRA_FIELD_USE_CASE     = 'cf[<custom-field-id>]'
JIRA_FIELD_USER_COUNT   = 'cf[<custom-field-id>]'
JIRA_FIELD_BUDGET_RANGE = 'cf[<custom-field-id>]'
JIRA_FIELD_DUPLICATE_FLAG = 'cf[<custom-field-id>]'
JIRA_TRANSITION_INTAKE  = '<transition-id>'
JIRA_TRANSITION_IN_PROGRESS = '<transition-id>'
JIRA_TRANSITION_APPROVED = '<transition-id>'
JIRA_TRANSITION_REJECTED = '<transition-id>'

// Notion
NOTION_API_TOKEN        = 'secret_<integration-token>'
NOTION_SOFTWARE_REGISTER_DB_ID = '<uuid-of-software-register-db>'
NOTION_CHECKLIST_DB_ID  = '<uuid-of-checklist-db>'
NOTION_SCORECARD_DB_ID  = '<uuid-of-scorecard-db>'
NOTION_CHECKLIST_TEMPLATE_PAGE_ID = '<uuid-of-checklist-template>'
NOTION_SCORECARD_TEMPLATE_PAGE_ID = '<uuid-of-scorecard-template>'

// Google Workspace
GOOGLE_SERVICE_ACCOUNT_JSON = '<base64-encoded-service-account-key-json>'
GOOGLE_IMPERSONATION_EMAIL  = 'itmanager@yourdomain.com'
GOOGLE_FORM_ID          = '<google-form-resource-id>'
APPROVAL_EMAIL_TEMPLATE_SUBJECT = '[ITEVAL] Tool Approval Request: {tool_name}'
MANAGER_EMAIL           = 'manager@yourdomain.com'
REMINDER_DELAY_HOURS    = '48'

// DocuSign
DOCUSIGN_INTEGRATION_KEY   = '<client-id-from-docusign-app>'
DOCUSIGN_USER_ID           = '<impersonated-user-guid>'
DOCUSIGN_ACCOUNT_ID        = '<docusign-account-guid>'
DOCUSIGN_RSA_PRIVATE_KEY   = '<pem-encoded-rsa-private-key>'
DOCUSIGN_TEMPLATE_ID       = '<envelope-template-guid>'
DOCUSIGN_SIGNER_ROLE_VENDOR = 'Vendor Signatory'
DOCUSIGN_SIGNER_ROLE_IT    = 'IT Manager'
DOCUSIGN_SIGNER_ROLE_FINANCE = 'Finance Controller'
DOCUSIGN_CONNECT_HMAC_KEY  = '<hmac-secret-for-connect-validation>'
DOCUSIGN_ENV               = 'demo'  // change to 'production' at go-live

// Slack
SLACK_BOT_TOKEN         = 'xoxb-<bot-token>'
SLACK_ROLLOUT_CHANNEL_ID = 'C<channel-id>'

// General
ONBOARDING_DOCS_BASE_URL = 'https://notion.so/your-org/onboarding'
IT_MANAGER_NAME          = 'Marcus Dell'
IT_MANAGER_EMAIL         = 'marcus.dell@yourdomain.com'