KPI API Integration (Pull)

Audience: Admin, Developer
Page Type: How-To + Reference
Plan Feature: kpi_api_integration (must be enabled for your tenant)

---

Overview

COS can automatically pull KPI measurement data from external APIs on a scheduled basis. This is the pull integration model — COS calls your API endpoints at defined intervals and writes the extracted values as KPI measurements.

How It Works

External API  ←──── COS (cron schedule) ────→  KPI Measurement Table
   (your BI tool,       HTTP GET/POST             (auto-populated)
    data warehouse,      + auth headers
    monitoring system)   + JSONPath extraction

1. You define an Integration Endpoint (base URL + auth credentials)
2. You create KPI Bindings linking specific KPIs to API response fields
3. COS calls the API on a cron schedule and extracts values using JSONPath
4. Extracted values are written as measurements to the appropriate KPI

---

Prerequisites

• Plan Feature: kpi_api_integration must be enabled for your tenant
• Permission: User must have integration:manage permission (typically Admin or Strategy Manager)
• External API: Your data source must be accessible via HTTP/HTTPS

---

Step 1: Create an Integration Endpoint

An endpoint defines the external API connection details.

Navigate to: KPI Detail → Integration Panel → Manage Endpoints

Required Fields

Field	Description	Example
Name	Descriptive name	"BI Dashboard API"
Base URL	API base URL	https://api.example.com/v1
Auth Type	Authentication method	See Auth Types
Credentials	Auth credentials (encrypted at rest)	Depends on auth type

Supported Auth Types

Auth Type	Credentials	Header Sent
NONE	—	No auth header
BEARER_TOKEN	{ token: "..." }	Authorization: Bearer {token}
BASIC_AUTH	{ username: "...", password: "..." }	Authorization: Basic {base64}
API_KEY_HEADER	{ headerName: "X-API-Key", headerValue: "..." }	{headerName}: {headerValue}
API_KEY_QUERY	{ queryName: "api_key", queryValue: "..." }	?{queryName}={queryValue} appended to URL

---

Step 2: Create a KPI Binding

A binding connects a specific KPI to an API endpoint with response mapping rules.

Required Fields

Field	Description	Example
KPI	The KPI to receive measurements	(auto-selected from context)
Endpoint	Which integration endpoint to call	"BI Dashboard API"
Path Suffix	Appended to base URL	/metrics/revenue
Response Mapping	JSONPath expressions for value extraction	See below
Cron Expression	Schedule (e.g., hourly, daily)	0 */6 * * * (every 6 hours)

Response Mapping (JSONPath)

The response mapping tells COS how to extract numeric values from the API response JSON.

Field	Description	JSONPath Example
actual	Required. The current metric value	$.value, $.data.metrics.current
target	Optional. Target/goal value	$.target, $.data.metrics.target
forecast	Optional. Forecast value	$.forecast
statusNote	Optional. Text note	$.status

Example API Response:

{
  "metric": "revenue",
  "value": 1250000,
  "target": 1500000,
  "unit": "USD"
}

Response Mapping:

{
  "actual": "$.value",
  "target": "$.target"
}

JSONPath Patterns for Common Formats

API Format	JSONPath for actual
Flat: { "value": 42 }	$.value
Nested: { "data": { "metrics": { "current": 42 } } }	$.data.metrics.current
Array (last): { "series": [{ "value": 40 }, { "value": 42 }] }	$.series[-1:].value
Named key: { "kpis": { "revenue": { "actual": 42 } } }	$.kpis.revenue.actual
Paginated: { "results": [{ "measurement": 42 }] }	$.results[0].measurement

---

Step 3: Test and Activate

1. After creating the binding, click Test (Dry Run) to verify:
   • API is reachable
   • Auth credentials are valid
   • JSONPath extraction returns expected values
2. Review the extracted values in the test result
3. Once confirmed, the binding will run automatically on the defined cron schedule

Execution Logs

Each integration run creates a log entry with:

• HTTP status code
• Response time
• Extracted values
• Error message (if failed)
• Request/response details (sanitized)

---

Plan Feature Limits

Feature Key	Description	Default
kpi_api_integration	Enable/disable pull integration	Disabled
max_api_integrations	Max binding count per tenant (-1 = unlimited)	-1
min_cron_interval_minutes	Minimum cron interval allowed	60 min

---

Testing with Mock API

COS provides a built-in mock API for testing integrations without needing a real external system.

Location: tools/mock-kpi-api/

cd tools/mock-kpi-api && npm install && npm start
# → http://localhost:4444

The mock API supports all 5 auth types and various response formats. See Mock API Testing Guide for details.

---

Supported KPI Types

Pull integration works with all KPI types in COS:

KPI Entity Type	Source Module
THEME_KPI	Strategic Theme KPIs
BSC_KPI	Balanced Scorecard KPIs
ASIS_KPI	Current State (As-Is) KPIs
SWOT_KPI	SWOT Analysis KPIs
PESTLE_KPI	PESTLE Analysis KPIs
KPI_DEFINITION	KPI Library KPIs
OKR_KEY_RESULT	OKR Key Result measurements
PRODUCT_SCORECARD_KPI	Product Scorecard KPIs

---

See also

• Integrations Overview
• Mock API Testing Guide
• API Overview
• Authentication & Tokens