Integration and API Spec

Integration and API Spec

System Backup Monitoring

Polled daily by Agent 1 (Backup Status Collector) to retrieve all backup job session results from the past 24 hours. The API returns structured job session objects including job name, status, start time, end time, and error message. No webhook is available on-premises; the automation platform initiates the connection on schedule.

// Input
GET /api/v1/backupSessions
  ?createdAfter=2024-05-05T06:00:00Z
  &limit=500
Authorization: Bearer {access_token}

// Output (per session object)
{
  "id": "uuid",
  "name": "Job_ServerName_Daily",
  "jobId": "uuid",
  "result": "Success | Warning | Failed | None",
  "startTime": "2024-05-05T01:00:00Z",
  "endTime": "2024-05-05T01:45:00Z",
  "message": "Error string or empty"
}

Used by Agent 1 to read the expected job list and by Agent 3 (Audit Log Writer) to append daily result rows to the audit log. Two separate sheet tabs are used: one read-only reference tab (expected jobs) and one append-only log tab (audit log). The service account must have Editor access to the spreadsheet.

// Input: Read expected job list
GET https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}
  /values/{EXPECTED_JOBS_RANGE}

// Output: Expected job array
{ "values": [
    ["Job_ServerName_Daily", "server", "critical", "U012AB3CD"],
    ["Job_CloudVolume_Nightly", "cloud", "warning", "U098XY7ZZ"]
  ]
}

// Input: Append audit log row (Agent 3)
POST https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}
  /values/{AUDIT_LOG_RANGE}:append
  ?valueInputOption=RAW&insertDataOption=INSERT_ROWS
Body: { "values": [["2024-05-05", "Job_ServerName_Daily",
  "Failed", "critical", "OPS-1042", "PD-8821",
  "Agent service not running", "2024-05-05T06:03:12Z"]] }

Used by Agent 2 (Failure Classifier and Escalation Agent) to create one incident ticket per failed or missing backup job. Ticket fields are pre-populated from the structured result list produced by Agent 1. No webhook from Jira is consumed by the automation; all calls are outbound from the platform.

// Input: Create issue
POST {JIRA_BASE_URL}/rest/api/3/issue
Authorization: Basic base64(email:token)
Content-Type: application/json

{
  "fields": {
    "project": { "key": "{JIRA_PROJECT_KEY}" },
    "issuetype": { "id": "{JIRA_ISSUE_TYPE_ID}" },
    "summary": "Backup failure: Job_ServerName_Daily [critical]",
    "description": { "type": "doc", "version": 1,
      "content": [{ "type": "paragraph", "content":
        [{ "type": "text", "text": "Error: Agent service not running. Run date: 2024-05-05" }]
      }]
    },
    "priority": { "name": "Highest" },
    "customfield_10050": "ServerName",
    "customfield_10051": "Job_ServerName_Daily"
  }
}

// Output
{ "id": "10204", "key": "OPS-1042",
  "self": "https://yourcompany.atlassian.net/rest/api/3/issue/10204" }

Used by Agent 2 to post failure alerts to a designated channel or as a direct message to the on-call owner identified in the expected job list. The Slack app is installed to the workspace once during setup; the bot token is stored in the credential store.

// Input: Post alert message
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
Content-Type: application/json

{
  "channel": "U012AB3CD",
  "text": "Backup failure detected",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": ":red_circle: *CRITICAL* | Job_ServerName_Daily failed\n
      Error: Agent service not running\n
      Ticket: <https://yourcompany.atlassian.net/browse/OPS-1042|OPS-1042>\n
      Run date: 2024-05-05 06:00 UTC" } }
  ]
}

// Output
{ "ok": true, "channel": "U012AB3CD", "ts": "1714893712.000100" }

Used by Agent 2 for critical-severity failures only. The automation platform sends a trigger event to the PagerDuty Events API using a service-level integration key. PagerDuty then applies the pre-configured on-call schedule and escalation policy to route the incident to the correct responder. The automation does not manage PagerDuty schedules; those must be configured in PagerDuty independently.

// Input: Trigger critical incident
POST https://events.pagerduty.com/v2/enqueue
Content-Type: application/json

{
  "routing_key": "{PAGERDUTY_ROUTING_KEY}",
  "event_action": "trigger",
  "dedup_key": "OPS-1042-2024-05-05",
  "payload": {
    "summary": "CRITICAL backup failure: Job_ServerName_Daily",
    "severity": "critical",
    "source": "FullSpec Backup Monitor",
    "timestamp": "2024-05-05T06:03:12Z",
    "custom_details": {
      "job_name": "Job_ServerName_Daily",
      "error_message": "Agent service not running",
      "jira_ticket": "OPS-1042",
      "system_type": "server"
    }
  }
}

// Output
{ "status": "success", "message": "Event processed",
  "dedup_key": "OPS-1042-2024-05-05" }

Used by Agent 2 for critical-failure email escalation to the IT manager or business owner, supplementing the PagerDuty alert. The Gmail API sends a structured email from a designated service account or delegated mailbox. This channel is used only for critical severity classifications.

// Input: Send escalation email
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer {access_token}

{ "raw": "<base64url-encoded MIME message>" }

// Decoded MIME structure
From: backup-monitor@yourcompany.com
To: itmanager@yourcompany.com
Subject: [CRITICAL] Backup failure: Job_ServerName_Daily - 2024-05-05
Content-Type: text/plain; charset=utf-8

CRITICAL backup failure detected.
Job: Job_ServerName_Daily | System: server
Error: Agent service not running
Jira: https://yourcompany.atlassian.net/browse/OPS-1042
PagerDuty: https://yourcompany.pagerduty.com/incidents/PD-8821
Run date: 2024-05-05 06:00 UTC

// Output
{ "id": "18f3c2d9a1b4e5f6", "threadId": "18f3c2d9a1b4e5f6",
  "labelIds": ["SENT"] }

// Veeam
VEEAM_HOST                  = "https://veeam.internal:9419"
VEEAM_API_USER              = "<api-read-only-user>"
VEEAM_API_PASSWORD          = "<api-user-password>"

// Google (shared for Sheets and Gmail if using Service Account)
GOOGLE_SERVICE_ACCOUNT_JSON = "<full JSON key file contents>"
GOOGLE_SPREADSHEET_ID       = "<sheets-doc-id-from-url>"
EXPECTED_JOBS_RANGE         = "ExpectedJobs!A2:D"
AUDIT_LOG_RANGE             = "AuditLog!A:H"

// Gmail (OAuth flow; only if NOT using service account delegation)
GMAIL_CLIENT_ID             = "<oauth-client-id>"
GMAIL_CLIENT_SECRET         = "<oauth-client-secret>"
GMAIL_REFRESH_TOKEN         = "<offline-refresh-token>"
GMAIL_FROM_ADDRESS          = "backup-monitor@yourcompany.com"
GMAIL_ESCALATION_TO         = "itmanager@yourcompany.com"

// Jira
JIRA_BASE_URL               = "https://yourcompany.atlassian.net"
JIRA_USER_EMAIL             = "automation@yourcompany.com"
JIRA_API_TOKEN              = "<atlassian-api-token>"
JIRA_PROJECT_KEY            = "OPS"
JIRA_ISSUE_TYPE_ID          = "<numeric-issue-type-id>"

// Slack
SLACK_BOT_TOKEN             = "xoxb-<workspace-bot-token>"
SLACK_ALERT_CHANNEL_ID      = "<channel-id-not-name>"

// PagerDuty
PAGERDUTY_ROUTING_KEY       = "<32-char-integration-key>"

// Platform config constants (not secrets; stored as env vars)
SCHEDULE_TIME_LOCAL         = "06:00"
LOOKBACK_HOURS              = 24
MAX_VEEAM_PAGE_SIZE         = 500
SLACK_INTER_MESSAGE_DELAY_MS = 100
JIRA_INTER_REQUEST_DELAY_MS  = 200