04 — Runbook: Adventive Looker Studio Connector¶

Ownership¶

Primary owner: Adventive Platform Engineering
Secondary: Adventive API team (upstream data source)
Issue escalation: Adventive support ticket — https://help.adventive.com/en/knowledge/kb-tickets/new

Tier¶

Criticality: Tier-2 — The connector is customer-facing and serves paying advertisers. An outage prevents customers from accessing their campaign analytics in Looker Studio. It does not affect ad serving or billing.

What this connector does¶

The Adventive Looker Studio connector is a Google Apps Script Community Connector that allows Looker Studio users to build custom reports using their Adventive campaign analytics data. It authenticates using an Adventive Integration Key and API Key, fetches impression, click, engagement, and video metrics from the Adventive Analytics API, and caches responses for 30 minutes to reduce API load. The connector is published to the Looker Studio connector gallery and available to all Adventive customers with API access enabled.

API dependencies¶

Dependency	Endpoint	Expected latency	Timeout	Failure behavior
Adventive Analytics API — data	`GET /v2.0/dataconnector.json`	< 3 s	10 s	User error: "connector could not retrieve data"
Adventive Analytics API — auth	`GET /v2.0/credentialscheck.json`	< 1 s	10 s	`validateCredentials` returns false → "Invalid credentials"
Google CacheService	`CacheService.getUserCache()`	< 50 ms	n/a	Cache miss; connector falls through to API

Secrets / credentials¶

The connector does not hold any long-lived secrets. Per-user credentials are stored in PropertiesService.getUserProperties() under:

dscc.username — Adventive Integration Key
dscc.password — Adventive API Key

These are user-scoped properties. Only the authenticated Looker Studio user can read their own credentials. They cannot be accessed by Adventive engineers.

Observability¶

Cloud Logging¶

Log entries for the Apps Script project appear in Google Cloud Console → Logging → Log Explorer for the Apps Script project's associated Cloud project.

Useful log filter:

resource.type="app_script_function"

Expected log entries on a healthy data request:

Fetching data. Date range: 20260101 - 20260131
Cached data available.   (or)
Cached data not found, or unavailable. Attempting to fetch data from Adventive API...
Putting data in cache...

Red flags in logs: - Any line containing Error occurred or Exception - Any line that appears to contain credential values (should not appear after the security fix in §02) - Repeated Attempting to fetch data from Adventive API... lines with no Putting data in cache... following (indicates API failures)

No dashboards or alerts are currently configured¶

A monitoring improvement recommendation: set up a Cloud Logging metric for severity >= ERROR on the Apps Script project and alert to the platform Slack channel.

Common failure modes¶

Symptom: "Invalid credentials" error when credentials are correct¶

Check: 1. Has the user's API Key been rotated in the Adventive platform? (/v2.0/credentialscheck.json returning 401 for their specific key) 2. Is the Adventive API reachable? Test: curl -I https://api.adventive.com/v2.0/credentialscheck.json 3. Check Cloud Logging for the Apps Script project for any exception details

Mitigation: - Ask the user to regenerate their API Key in the Adventive platform and re-enter credentials in Looker Studio (Edit connection → re-enter keys) - If the API is unreachable, escalate to the Adventive API team

Rollback: Not applicable — this is a credentials or upstream issue, not a connector code issue.

Symptom: Report shows no data / spinner that never resolves¶

Check: 1. Is this a first load (cache miss) or a refresh? 2. Check Cloud Logging — is fetchDataFromApi being called and completing? 3. Is the date range valid? Very large date ranges (> 6 months) may produce API responses that exceed CacheService limits even with chunking. 4. Is the Adventive API returning data for the selected date range?

Mitigation: - Ask the user to try a smaller date range (7 days) to isolate whether the issue is data volume or API availability - If the issue only occurs on large ranges: this is a known limitation of CacheService chunking; no fix without architectural change

Rollback: If this started after a recent deploy, follow the rollback procedure in §03.

Symptom: Report data is stale / not updating¶

Check: 1. Is the user within the 30-minute cache window? Cache TTL is 1800 seconds. 2. Did the user change the date range or add new fields? The cache key includes the date range and field list — a different combination forces a cache miss.

Mitigation: - Advise the user to change the date range by one day and change it back to force a cache miss - Cache expires automatically after 30 minutes; no manual intervention needed

Symptom: `SyntaxError: Unexpected token` or JSON parse errors in logs¶

Check: - This indicates the fetchDataFromApi bug (BUG-1 in §02) is present — the connector is returning the HTTPResponse object rather than the content text. - Check which version is deployed: clasp deployments

Mitigation: - Apply the connector-rewrite files (GitHub) and deploy a new version (§03) - This is a critical bug that prevents all non-cached data fetches

Symptom: All executions fail with `SyntaxError: Invalid or unexpected token` or `ReferenceError: XML is not defined`¶

Check: - This suggests a Rhino-only feature slipped into the codebase — most commonly a for each…in loop, __iterator__, an XML literal, or a conditional catch clause. - Check recent git history for the file listed in the stack trace.

Mitigation: - See §05 — V8 Runtime Migration — Things to avoid when editing this connector on V8. Remove the offending Rhino-only construct and redeploy via §03. - Add a test that exercises the affected code path so the regression is caught before it reaches production next time.

Symptom: Looker Studio reports "This script is no longer available" / requests time out at the platform layer¶

Check: - If the error is not in Cloud Logging for the Apps Script project (i.e., the script is not being executed at all), the most likely cause is that the project is still on the retired Rhino runtime. - Verify via Apps Script editor → Project Settings → runtimeVersion in the manifest.

Mitigation: - Follow the migration procedure in §05 — V8 Runtime Migration. Do not skip the pre-V8 snapshot step — it is the only rollback path if the flip surfaces a latent bug.

Symptom: Connector not appearing in Looker Studio gallery¶

Check: - Has the marketplace listing been updated after the last clasp deploy? (See §03 — Marketplace publishing) - Is the connector still in a published state in the Looker Studio connector settings?

Mitigation: - Re-publish via the Workspace Marketplace SDK (§03) - Allow up to 24 hours for the listing to propagate

Deploy notes¶

Standard deploy: Follow §03 — push to staging, verify, then push to production and create a versioned deployment.
Staging soak: Minimum 2 hours for code changes before production deploy.
Break-glass: If a critical production bug requires an immediate fix (e.g., credentials being leaked in logs), the Platform lead can approve a direct production push. Document the approval in the platform Slack channel with the commit SHA and reason.
Post-deploy: Run the verification checklist from §03 against production before closing the deploy.

Back to: README