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: The integration menu/API permission (KPI_INTEGRATION_BINDING) and authority on the target: for a KPI, edit authority on that KPI (KPI edit permission + responsible, owner/parent unit leader or an administrator role); for a key result, the existing OKR authority
• 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: Goals & Tracking → KPI Tracking → KPI detail → Integration tab → 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
Target	The KPI register KPI (kpiType: KPI) or OKR key result (OKR_KEY_RESULT) that receives measurements	(auto-selected from the KPI you opened)
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. Missing/null/blank inherits this exact KPI's latest target; explicit 0 wins. Without a usable previous target, 0 is stored.	$.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.

---

Binding targets and rules

Breaking change (KPI register)

Bindings no longer point to per-report KPI copies but to one of two target types:

kpiType	Target
KPI	A KPI in the KPI register. Pulled values appear in every report that uses the KPI.
OKR_KEY_RESULT	An OKR key result

The former family types (THEME_KPI, BSC_KPI, ASIS_KPI, SWOT_KPI, PESTLE_KPI, KPI_DEFINITION, PRODUCT_SCORECARD_KPI) return 400. Former family bindings were removed; recreate them on the KPI register KPI if needed.

• Authority is rechecked on every run. Scheduled and manual pulls run with the authority of the user who created the binding (or who last changed what is fetched). If that person has lost authority, nothing is written.
• Changing or deleting a binding also requires authority on the target.
• Retired KPI: Retiring a KPI deactivates its bindings; reactivation does not re-enable them automatically.
• Measurement date (0.5.0): for a KPI target the measurement date is the last day of the current period per the KPI's measurement frequency (UTC; monthly KPI → month end). Runs in the same period update the same record.
• Key result (0.5.0): each run updates the key result's "Actual" field (and the target when mapped); progress is calculated as for manual entry. No separate measurement record is added. In an approved OKR plan a target different from the stored value fails the run (OKR_LOCKED); the actual value stays writable.
• Value format: the pulled value must be a finite number or a plain decimal string ("44.5"). Values such as "N/A", "1,234" or "87 %" fail the run with nothing written. Category weight (weights) paths were removed from categorized mappings.
• Closed OKR cycle: A key result whose cycle is CLOSED or COMPLETED is skipped and the run log records the reason CYCLE_LOCKED.
• Closed reports or a closed planning period do not block pull writes to an active KPI.
• Header redaction: Configured header values are shown as [REDACTED] in binding responses, run logs and diagnostics. A [REDACTED] value sent back while editing keeps the stored value.
• Bindings are visible only to users who can see the target KPI (or key result).
• Every pull write appears in the KPI's History tab with the Pull integration channel and the Integration binding authority path.

---

See also

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