Clari Contract Validation in CI

Overview

Keep the required CI lane deterministic and credential-free. Test only owned endpoints and transformations offline, while running any provider-connected smoke test as an explicit, non-blocking or separately authorized environment gate.

Prerequisites

• Pinned endpoint and schema manifest for each used surface
• Synthetic fixtures for success, empty, throttled, aborted, malformed, and drifted responses
• Secret scanner and artifact-retention policy

Instructions

Step 1: Pin the contract evidence

Record provider URL, contract version, content fingerprint, extraction date, and the subset of operations the integration owns.

Step 2: Test request construction

Assert exact hosts, methods, paths, headers by name, payload schemas, timeouts, and prohibited mutation defaults.

Step 3: Test lifecycle behavior

Simulate queue, poll, terminal result, cancellation, pagination, 429, timeout, and restart from durable state.

Step 4: Test data gates

Assert schema validation, reconciliation, unknown-field quarantine, redaction, and atomic publication behavior.

Step 5: Scan outputs

Fail on credential patterns, real customer fixtures, unredacted headers, or sensitive payloads in logs and snapshots.

Step 6: Separate live smoke testing

If authorized, run one minimal non-production read with a short timeout and store only a redacted receipt outside the deterministic required lane.

Authentication

Required CI must use dummy credentials and no provider network access. Any live smoke credential comes from protected environment secrets, is restricted to non-production reads, and is never available to forked or untrusted jobs.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Deterministic contract-test and schema-diff reports
• Secret and test-data hygiene results
• Optional live-smoke receipt clearly separated from required CI

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A pull request proves forecast job-state handling and warehouse rollback entirely from synthetic fixtures. A protected post-merge job performs one /admin/limits read and publishes only status and timestamp.

Error Handling

Clari API Failure Triage

Overview

Classify the failure before retrying it. Separate transport, authentication, authorization, entitlement, quota, job-state, request-shape, schema, and data-scope failures so recovery does not create duplicate jobs or leak sensitive payloads.

Prerequisites

• Surface, base URL, endpoint, method, timestamp, and environment
• Redacted status, headers, error code or ID, and job ID when present
• Expected hierarchy, forecast, workspace, entity, and time-window scope

Instructions

Step 1: Reconstruct the boundary

Confirm host, API version, method, headers by name, request shape, and the identity used without revealing credential values.

Step 2: Classify HTTP and provider state

Distinguish 401, 403, 428, 429, 5xx, empty success, schema rejection, and non-terminal or aborted job states.

Step 3: Check authorization and entitlement

Verify Forecast Tab access, hierarchy opt-in, product entitlement, workspace membership, partner enablement, and entity configuration.

Step 4: Check quota and duplication risk

Read available limits when supported, inspect existing jobs, and avoid re-queuing a request whose outcome is merely unknown.

Step 5: Reduce to a safe reproduction

Use the smallest read-only or synthetic request that preserves the failure and remove customer values from the artifact.

Step 6: Choose recovery and prove it

Rotate or re-scope credentials, repair the request, wait for capacity, migrate schema, or escalate with a redacted receipt; then rerun exactly one bounded verification.

Authentication

Never print apikey, partnerkey, X-Api-Key, or X-Api-Password. A 200 response with empty data is not proof of correct authorization; validate the effective hierarchy and workspace separately.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Failure classification and ruled-out causes
• Minimal redacted reproduction with contract version
• Recovery action, verification result, and escalation bundle if unresolved

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A forecast request returns no rows. The operator confirms the job was DONE, then finds the integration user was not opted into the requested hierarchy; access is cor…

Clari Forecast Warehouse Pipeline

Overview

Move forecast data through a three-stage pipeline: immutable landing, validated normalization, and reconciled publication. Preserve Clari identifiers and export context so every dashboard value can be traced back to one job and request.

Prerequisites

• Forecast ID, hierarchy scope, fiscal-period convention, and requested data types
• Landing storage with encryption, retention, and access controls
• Warehouse schema owner and reconciliation tolerances

Instructions

Step 1: Define the snapshot key

Use forecast ID, requested time period, scope, currency, data types, and export timestamp as the immutable business key.

Step 2: Reserve export capacity

Read organization limits and ensure the scheduler will not exceed concurrent or rolling quota constraints.

Step 3: Run the asynchronous export

Queue the forecast job, poll boundedly to a terminal state, and retrieve the result only after DONE.

Step 4: Land before transforming

Write the original approved result to immutable, access-controlled storage with job ID, content hash, contract fingerprint, and ingestion timestamp.

Step 5: Normalize and reconcile

Map fields into versioned tables, preserve raw identifiers, check row counts and totals, and quarantine unknown fields or malformed monetary values.

Step 6: Publish atomically

Expose the new snapshot only after reconciliation passes; otherwise keep the prior known-good snapshot and emit an actionable failure receipt.

Authentication

Use a dedicated Revenue API integration identity and apikey header. Warehouse credentials must be separate from the Clari token, and logs must exclude both secrets and raw forecast values.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Immutable landing manifest tied to the Clari job ID
• Versioned normalized tables with lineage and schema checks
• Reconciliation report and atomic publish or rollback decision

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A quarterly forecast export lands as an immutable object, normalizes forecast and quota rows, reconciles counts and totals against the landing file, and advances the dashboard view only after all gates pass.

Error Handling

Clari Copilot Conversation Intelligence Extraction

Overview

Treat Copilot as a separate data product rather than an extension of Revenue API exports. Build a metadata-first extraction that minimizes sensitive content, joins stable identifiers, and records the exact window and pagination boundary.

Prerequisites

• Copilot API key/password pair stored in an approved secret manager
• Authorized time window, user population, and data-classification decision
• Destination controls suitable for call and participant data

Instructions

Step 1: Inventory the required resources

Choose only the calls, call details, users, topics, scorecards, and templates necessary for the approved use case.

Step 2: Freeze the extraction window

Record workspace, start and end time, pagination order, and inclusion rules so reruns are deterministic.

Step 3: Fetch metadata first

List users, topics, scorecard templates, and call summaries before requesting detailed call content.

Step 4: Retrieve bounded details

Request call details only for selected call IDs, honor both documented rate ceilings, and checkpoint pagination without duplicates.

Step 5: Normalize with privacy controls

Separate identities, call metadata, scoring, and sensitive content; tokenize joins and restrict transcript or recording access.

Step 6: Reconcile and publish

Compare requested and received IDs, record missing or changed calls, and publish only the authorized dataset with lineage.

Authentication

Send both X-Api-Key and X-Api-Password to the Copilot host over HTTPS. Do not substitute the Revenue apikey; redact both Copilot credentials and minimize logs containing call titles, participant data, transcripts, or recording links.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Windowed extraction manifest and pagination checkpoints
• Governed call, user, topic, and scorecard datasets
• Reconciliation, privacy-classification, and publication receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A coaching dataset lists calls for one approved week, selects only calls for an authorized team, retrieves details under the documented limits, tokenizes participant joins, and records missing IDs before publication.

Error …

Clari Export and Data-Cost Governance

Overview

Optimize total integration consumption without inventing public Clari price claims. Provider request capacity, large result transfer, raw-data retention, repeated transformations, and warehouse scans are measurable levers even when commercial pricing is contract-specific.

Prerequisites

• Export and Copilot request counts by workload and owner
• Result bytes, rows, retention, storage, and warehouse scan metrics
• Freshness, recovery, audit, and analytical requirements

Instructions

Step 1: Attribute consumption

Tag every scheduled or ad hoc request with owner, business outcome, surface, window, selected data, and destination.

Step 2: Measure the full path

Track export quota, Copilot calls, result size, transfer, landing retention, transformation compute, warehouse storage, and query scans.

Step 3: Remove redundant work

Reuse immutable approved snapshots, coalesce identical requests, narrow history and fields, and resume from checkpoints instead of full reruns.

Step 4: Set freshness tiers

Give operational, analytical, audit, and backfill workloads explicit cadences and defer low-value work when quota or budget is constrained.

Step 5: Tune retention and layout

Keep raw data only as policy requires, compact normalized data, partition by access pattern, and preserve lineage even when payloads expire.

Step 6: Review tradeoffs

Compare consumption savings with freshness, recovery, correctness, and compliance impact before promoting a change.

Authentication

Consumption telemetry must contain credential references and workload identifiers, never secret values or sensitive payloads. Do not create additional tokens to bypass organization limits.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Workload-level consumption and ownership ledger
• Quota, request, storage, and warehouse budget policy
• Before/after savings with freshness, correctness, and recovery impact

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A team replaces six overlapping quarterly exports with one immutable snapshot shared by approved consumers, retains raw data only for the required window, and preserves separate transformations and lineage.

Error Handling

Clari Redacted Support Bundle

Overview

A useful support bundle explains what happened without copying credentials or customer payloads. Collect identifiers, timing, states, hashes, schema summaries, and controlled samples under a manifest that is reviewable before sharing.

Prerequisites

• Incident ID, owner, environment, surface, and affected window
• Exact endpoint and method inventory plus provider job IDs or cursors
• Approved redaction rules, retention, and sharing destination

Instructions

Step 1: Create the manifest

Record collector version, contract fingerprint, host, endpoint names, request fingerprints, timestamps, and system versions.

Step 2: Collect control-plane evidence

Capture HTTP statuses, redacted response headers, error codes or IDs, job state transitions, attempts, waits, and scheduler ownership.

Step 3: Collect data-plane summaries

Record content type, byte and row counts, field names, schema hash, and reconciliation deltas without raw revenue, identity, transcript, or recording data.

Step 4: Collect local health

Include deployment version, checkpoint state, queue depth, destination health, and relevant redacted logs.

Step 5: Scan and review

Search for all credential header names, token patterns, emails, names, deal values, transcript text, and signed URLs; require human review before sharing.

Step 6: Seal and expire

Hash the bundle, encrypt it, record recipients and expiry, and delete working copies according to incident policy.

Authentication

Never collect values for apikey, partnerkey, X-Api-Key, or X-Api-Password. If a credential may have entered any artifact, stop distribution and rotate it before continuing.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Redacted manifest and evidence inventory
• Job or cursor timeline plus schema and reconciliation summaries
• Bundle hash, reviewer, recipients, expiry, and deletion receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A stuck forecast incident bundle includes the job ID, STARTED timeline, provider error ID, contract hash, scheduler version, and empty-result schema—but no token, forecast rows, or user email addresses.

Error Handling

Deploy a Clari Scheduled Data Pipeline

Overview

Deploy orchestration rather than embedding long-running polling in ephemeral request handlers. Ensure one logical scheduler owns each workload, persists provider job IDs or cursors before waiting, and separates landing from publication.

Prerequisites

• Versioned container or runtime artifact and infrastructure manifest
• Per-surface credential references and least-privilege identity
• Durable checkpoint store, encrypted landing zone, and atomic publish mechanism

Instructions

Step 1: Package the worker

Pin dependencies and contract fingerprints, run as a non-root identity, and expose no inbound endpoint unless operationally required.

Step 2: Inject configuration

Supply base URLs, credential references, forecast or workspace scope, cadence, limits, destination, and retention through managed configuration.

Step 3: Enforce single-writer scheduling

Use a lease or platform concurrency rule so overlapping invocations cannot queue duplicate exports or replay mutations.

Step 4: Persist before polling

Write the request fingerprint and returned job ID or Copilot cursor durably before any wait, retry, or process exit.

Step 5: Publish through gates

Land, validate, reconcile, and atomically advance the destination only after the provider operation and local checks succeed.

Step 6: Roll out and roll back

Canary one bounded workload, compare service levels and data, then promote; retain the prior artifact and checkpoint reader for reversal.

Authentication

Mount only the credentials needed by the selected surface and environment. Prevent secret values and provider payloads from entering process arguments, deployment diffs, health endpoints, or logs.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Immutable deployment artifact and configuration manifest
• Scheduler ownership, lease, checkpoint, and retry policy
• Canary comparison and production promote or rollback receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

An orchestrator runs one quarterly forecast export at a time, persists the Clari job ID, resumes polling after a restart, validates the landing file, and atomically advances the warehouse snapshot.

Error Handling

First Clari Forecast Export

Overview

Prove the complete asynchronous export contract with one small, non-production forecast request. Success means retaining the forecast ID, job ID, terminal state, result format, and a redacted schema sample—not merely receiving an initial HTTP response.

Prerequisites

• Forecast Tab ID copied from the entitled Clari Forecast view
• A scoped Revenue API token stored outside the repository
• A small time period, hierarchy scope, and approved output location

Instructions

Step 1: Freeze the request

Record the forecast ID, time period, requested data types, scope ID, currency, history choice, and JSON or CSV format.

Step 2: Check capacity

Read /admin/limits and confirm both concurrent capacity and rolling monthly quota before consuming an export slot.

Step 3: Queue the export

Submit POST /export/forecast/{forecastId} against the documented Revenue API base and retain the returned job ID.

Step 4: Poll deliberately

Read /export/jobs/{jobId} with bounded backoff until DONE, ABORTED, or an operator-defined timeout. Do not treat SCHEDULED or STARTED as completion.

Step 5: Retrieve once

Only after DONE, fetch /export/jobs/{jobId}/results, validate content type and shape, and store the result in the approved temporary boundary.

Step 6: Close the proof

Record row count, schema fingerprint, status timeline, and cleanup result; delete temporary exported data according to policy.

Authentication

Use the Revenue API token only in the apikey header over HTTPS. Never include the header, raw response body, or revenue values in logs; authorization follows the token owner’s Clari access and hierarchy.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Redacted request manifest and returned job ID
• Terminal-state timeline and result schema fingerprint
• Pass/fail decision with cleanup receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

An operator requests a JSON export for one current-quarter Forecast Tab, observes SCHEDULED, STARTED, and DONE, retrieves the result once, and records field names and row count without re…

Clari Integration Identity and Token Setup

Overview

Establish a dedicated integration identity before building any data flow. Treat Revenue API tokens, ingestion partner keys, and Copilot key/password pairs as separate credentials with separate rotation and revocation paths.

Prerequisites

• Named business owner and technical owner for the integration
• Target surface: Revenue API, v2 ingestion, or Copilot API
• Approved secret manager and a non-production validation boundary

Instructions

Step 1: Choose the surface

Record the exact base URL and authentication contract: Revenue API uses the apikey header, v2 ingestion additionally requires partnerkey, and Copilot uses both X-Api-Key and X-Api-Password.

Step 2: Create a dedicated identity

Use a service or integration user whose hierarchy and forecast access match the intended export scope. Do not reuse a personal administrator credential.

Step 3: Issue and escrow credentials

Generate the credential in the Clari settings exposed for the entitled product, capture it once into the approved secret manager, and record owner and rotation metadata without copying the value into tickets or logs.

Step 4: Validate the smallest read

For Revenue API, call the administrative limits read or another entitled read-only endpoint. For Copilot, list a narrowly scoped resource such as users; do not create or update CRM records during authentication testing.

Step 5: Prove effective access

Confirm the identity can see only the expected organization, forecast hierarchy, workspace, and object set. Treat an empty result separately from successful authorization.

Step 6: Document rotation and revocation

Define overlap, rollback, dependent-job restart, and emergency revocation procedures before production use.

Authentication

Send credentials only in the provider-documented headers over HTTPS. Redact all token and password values, never persist them in shell history or fixtures, and remember that revoking a Revenue API token or deactivating its owning user can break active integrations.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Credential inventory containing references, owners, scopes, and rotation dates
• Redacted read-only validation receipt with endpoint, timestamp, and status
• Revocation and dependent-job recovery plan

Return the exact surface, environment, resource or job identifiers…

Clari Offline Contract Development Loop

Overview

Make offline development the default and live provider calls an explicit integration stage. Model the provider’s authentication headers, job transitions, pagination, error objects, and schema drift without storing secrets or production records.

Prerequisites

• Chosen Clari surface and pinned contract version or fingerprint
• Synthetic fixtures covering success, empty, partial, and failure responses
• Local secret scanning and test-data classification rules

Instructions

Step 1: Define the contract boundary

List endpoints, headers, request fields, response fields, job states, and pagination semantics used by the integration.

Step 2: Build synthetic fixtures

Create minimal payloads that preserve shapes and identifiers while containing no real people, accounts, calls, forecasts, or deal values.

Step 3: Simulate state transitions

Make the test server move deterministically through queued, running, completed, aborted, rate-limited, and timed-out paths.

Step 4: Exercise adapters

Run parser, schema, retry, pagination, idempotency, and redaction tests against the simulator with network access disabled.

Step 5: Add one gated live smoke test

Use a dedicated non-production identity and the smallest read-only request; skip it unless credentials and explicit integration-test approval are present.

Step 6: Refresh deliberately

When the provider contract changes, review the diff, update fixtures and assertions together, and retain the old failing fixture as migration evidence.

Authentication

Offline tests must use obvious dummy values. A gated live test may read credentials from the approved secret manager at runtime, but must never serialize headers or provider payloads into test output.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Pinned endpoint and schema contract manifest
• Synthetic fixture set with provenance and data-classification receipt
• Offline test report plus separately identified live-smoke result

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A local export client receives synthetic SCHEDULED, STARTED, and DONE responses, then a 429 and an ABORTED job. CI proves bounded retry and redaction witho…

Clari Pipeline Throughput Tuning

Overview

Tune from measured stage latency instead of increasing concurrency blindly. Provider queue time, polling, result transfer, parsing, reconciliation, and destination load are separate bottlenecks with different safe remedies.

Prerequisites

• Baseline p50, p95, and failure rate for each pipeline stage
• Request sizes, selected fields, periods, pages, and destination load profile
• Current organization limits and Copilot ceilings

Instructions

Step 1: Build the latency budget

Split the service-level objective across queue admission, provider execution, polling, transfer, validation, and publication.

Step 2: Locate the bottleneck

Correlate provider job timing, response size, page count, local CPU and memory, warehouse load, and retry delay.

Step 3: Reduce unnecessary work

Narrow forecast data types, history, scope, Copilot details, and rerun windows while preserving the approved analytical contract.

Step 4: Tune polling and paging

Use state-aware backoff, durable cursors, bounded page sizes, and streaming validation; do not poll faster than useful state changes.

Step 5: Use concurrency within evidence

Increase independent reads or transforms only inside reported provider and destination headroom, retaining a recovery slot.

Step 6: Canary and compare

Run the candidate against the same representative workload, compare correctness and cost signals, and roll back if either regresses.

Authentication

Performance telemetry must omit credentials and sensitive payloads. Never duplicate tokens across workers to evade organization or workspace limits.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Stage-level latency profile and identified bottleneck
• Tuning change with provider-capacity rationale
• Before/after correctness, latency, quota, and rollback results

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

Profiling shows warehouse parsing—not provider export time—dominates latency. The team streams validation and batches warehouse writes while leaving Clari concurrency unchanged.

Error Handling

Clari Integration Production Readiness

Overview

Convert production readiness into a fail-closed evidence bundle. A green decision requires proof of provider access, contract compatibility, data correctness, quota behavior, observability, security, recovery, and operator ownership.

Prerequisites

• Versioned release candidate and endpoint inventory
• Completed non-production happy-path and failure-path tests
• Change owner, business owner, security owner, and rollback authority

Instructions

Step 1: Verify identity and contracts

Confirm surface-specific credentials, effective scope, base URL, API version, schema fingerprint, and entitlement.

Step 2: Verify data correctness

Reconcile counts, identifiers, time periods, totals, pagination, and empty-result behavior against an approved source.

Step 3: Verify resilience

Exercise timeout, 429, provider 5xx, aborted job, partial load, schema drift, and restart from checkpoint.

Step 4: Verify security and privacy

Prove secret redaction, least privilege, encryption, retention, deletion, mutation gates, and sensitive-content minimization.

Step 5: Verify operations

Confirm dashboards, alerts, service-status dependency, runbook, support bundle, capacity headroom, and on-call ownership.

Step 6: Approve or reject

Record exact artifact hashes and approvers. Launch only when rollback is rehearsed and no required evidence is missing.

Authentication

Production secrets must be injected from the approved manager into the matching client and never copied into release artifacts. Verify rotation and emergency revocation before launch.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Signed readiness matrix with evidence links and hashes
• Go/no-go decision with explicit exceptions, owners, and expiry
• Rollback trigger, procedure, and rehearsed result

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A forecast pipeline passes reconciliation and restart tests but lacks a verified token revocation drill. The launch remains no-go until rotation and dependent-job recovery are demonstrated.

Error Handling

Clari Quota-Aware Request Scheduling

Overview

Model each Clari surface as its own constrained queue. Revenue exports consume organization-level concurrent and rolling quota capacity, ingestion can reject excess concurrent async jobs, and Copilot has documented per-second and weekly ceilings.

Prerequisites

• Request inventory split by Revenue export, ingestion, and Copilot
• Priority classes, latency objectives, and retry budget
• Durable job IDs, cursors, and deduplication keys

Instructions

Step 1: Read the applicable limits

Use /admin/limits for Revenue export capacity and record the Copilot 10-per-second and 100,000-per-week ceilings from the current contract.

Step 2: Allocate capacity

Reserve headroom for interactive or recovery work and assign explicit concurrency to each scheduler rather than letting every worker retry independently.

Step 3: Make work resumable

Persist export job IDs, ingestion job IDs, Copilot cursors, and request fingerprints before polling or retrying.

Step 4: Apply bounded backoff

Honor provider retry guidance when present; otherwise use capped exponential backoff with jitter and a maximum elapsed time.

Step 5: Prevent duplicate mutations

Before replaying a queue or ingestion request, reconcile retained state and provider jobs. Reads may resume from checkpoints; writes require an explicit idempotency decision.

Step 6: Measure and tune

Track queue delay, attempts, 429 rate, quota remaining, terminal latency, and abandoned work by surface.

Authentication

Limit reads and job polling still require the correct surface credential. Redact authentication headers and keep scheduler state free of secret values and customer payloads.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Per-surface capacity model and worker allocation
• Retry, checkpoint, and deduplication policy
• Quota dashboard with alert and shedding thresholds

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A scheduler permits at most the organization’s reported export concurrency minus one recovery slot, polls known job IDs with jitter, and independently throttles Copilot reads below both documented ceilings.

Error Handling

Clari Governed Integration Architecture

Overview

Separate control-plane state from sensitive data and isolate each provider surface behind its own adapter. The architecture should make job identity, cursor state, source lineage, schema versions, mutations, and published datasets independently auditable.

Prerequisites

• Business flows and read/write endpoint inventory
• Data-classification, retention, residency, and access requirements
• Recovery point, recovery time, freshness, and reconciliation objectives

Instructions

Step 1: Draw trust boundaries

Place Revenue, ingestion, Copilot, secrets, scheduler, state store, landing zone, validator, warehouse, and consumers in explicit zones.

Step 2: Separate provider adapters

Use distinct hosts, credential types, schemas, limiters, and mutation policies for each surface.

Step 3: Design durable control state

Persist request fingerprints, provider job IDs, cursors, terminal states, contract fingerprints, and retry decisions outside ephemeral workers.

Step 4: Design the data path

Land immutable results, validate and reconcile in quarantine, normalize with lineage, then atomically publish approved versions.

Step 5: Design failure containment

Prevent provider failure, schema drift, partial load, or unauthorized mutation from advancing consumer-facing data.

Step 6: Prove operability

Walk happy path, provider outage, quota exhaustion, credential rotation, schema drift, rollback, deletion, and support escalation.

Authentication

Keep credential issuance and rotation in a dedicated secrets boundary. Adapters receive references for only one surface and environment, while downstream processors receive data but no provider credentials.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Trust-boundary and data-flow diagram
• Component ownership and contract matrix
• Failure, recovery, rollback, retention, and deletion walkthrough

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

The Revenue adapter writes job state to a control store and results to restricted landing storage; a validator publishes normalized snapshots. Copilot uses a different adapter and sensitive-data zone, while ingestion is isolated behind an approval-gated writer.

Error Handling

Typed Clari REST Client Patterns

Overview

Wrap only the endpoints the application owns instead of inventing a broad unofficial SDK. Keep Revenue, v2 ingestion, and Copilot clients separate so their base URLs, headers, limits, schemas, and mutation policies cannot bleed across boundaries.

Prerequisites

• Endpoint inventory and pinned first-party contract fingerprint
• Language-native HTTP and schema-validation libraries
• Defined timeout, retry, logging, and secret-redaction policies

Instructions

Step 1: Split clients by surface

Create separate Revenue, ingestion, and Copilot transports with immutable base URLs and header builders.

Step 2: Model request and response types

Represent identifiers, timestamps, pagination, export job states, error bodies, and optional fields explicitly; reject unknown destructive actions by default.

Step 3: Centralize transport policy

Set connect and response timeouts, user-agent identity, bounded retries for eligible transient failures, and correlation metadata without logging credentials or payloads.

Step 4: Implement job primitives

Expose queue, status, cancel, and result operations as an explicit state machine; do not hide long-running work behind an unbounded method.

Step 5: Validate at the boundary

Schema-check provider responses before domain mapping and preserve the redacted original error ID when validation fails.

Step 6: Prove compatibility

Run offline contract tests, one non-production read smoke test, and a rollback test against the previously pinned client version.

Authentication

Construct apikey, partnerkey, X-Api-Key, and X-Api-Password headers only inside the matching transport. Accept secret references rather than literal values and guarantee header redaction in errors, traces, and snapshots.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Endpoint-scoped typed client and surface-specific transport policy
• Contract, retry, state-machine, and redaction tests
• Compatibility matrix tied to provider contract fingerprints

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A Revenue client returns a typed job handle from a forecast request and requires the caller to poll to DONE before fetching re…

Secure Clari Data Integration Boundary

Overview

Protect both control-plane credentials and the business data they unlock. Clari exports can contain hierarchy, identity, forecast, quota, CRM, activity, and conversation data, while ingestion and Copilot CRM endpoints can mutate provider state.

Prerequisites

• Integration data-flow diagram and endpoint inventory
• Named secret, privacy, retention, and incident owners
• Destination encryption, access-control, audit, and deletion capabilities

Instructions

Step 1: Classify every flow

Identify credentials, user and participant identifiers, revenue values, activity metadata, transcripts, recordings, and CRM objects by sensitivity.

Step 2: Minimize authority

Use dedicated identities, separate Revenue, ingestion, and Copilot secrets, narrow hierarchy or workspace access, and deny mutation endpoints unless required.

Step 3: Protect credentials

Store only references in configuration, redact all documented auth headers, rotate on schedule, and test revocation without exposing values.

Step 4: Protect data in motion and at rest

Require HTTPS, encryption, restricted landing zones, field-level minimization, retention limits, and governed deletion.

Step 5: Constrain mutations

Gate ingestion and Copilot create, update, or delete actions behind validation, reconciliation, explicit operator approval, and rollback planning.

Step 6: Exercise response

Test credential exposure, overbroad access, incorrect export publication, and unauthorized mutation scenarios; retain redacted evidence.

Authentication

Revenue apikey, ingestion partnerkey, and Copilot key/password credentials are distinct high-impact secrets. Never log them, accept them in free-form prompts, or reuse one surface’s credential in another client.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Threat model and data-classification matrix
• Least-privilege credential and endpoint policy
• Rotation, revocation, deletion, and incident drill receipts

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A pipeline grants a forecast integration user access only to the required hierarchy, stores raw exports in a restricted landing zone, publishes minimized aggregates, and denies ingestion and Copi…

Clari API and Schema Migration

Overview

Treat provider URL, authentication, request schema, job behavior, response schema, and destination mapping as one versioned contract. Prove the target alongside the current path before moving production traffic or published data.

Prerequisites

• Current and target hosts, versions, operations, schemas, and credential types
• Representative requests and expected reconciliations
• Dual-run environment, migration owner, and rollback deadline

Instructions

Step 1: Inventory the delta

Diff hosts, base paths, auth headers, methods, fields, enum values, errors, limits, pagination, and mutation semantics.

Step 2: Build an explicit mapping

Classify every used field and behavior as unchanged, renamed, transformed, added, removed, or unsupported.

Step 3: Update clients and fixtures

Pin the target contract, add target adapters and schemas, and retain current fixtures for regression and rollback testing.

Step 4: Dual-read safely

Run bounded non-production or approved parallel reads for identical windows and compare identifiers, counts, values, states, and latency.

Step 5: Cut over atomically

Move one workload or consumer at a time, retain the prior client and published snapshot, and stop on unexplained divergence.

Step 6: Retire with evidence

After the rollback window, remove legacy credentials and routes, update runbooks, and retain the comparison and revocation receipts.

Authentication

Do not reuse headers merely because two surfaces belong to Clari. Revenue, v2 ingestion, and Copilot each require their documented host and credentials; rotate or revoke legacy credentials only after rollback is no longer needed.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Contract delta and field-level compatibility map
• Dual-read reconciliation and performance report
• Cutover, rollback-window, legacy revocation, and retirement receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

A client moves from an old Copilot host to rest-api.copilot.clari.com, validates the two-header authentication contract, dual-reads one approved week, reconciles call IDs, then revokes the legacy credential after the rollback window.

Error Handling

Clari Audit and Activity Change Feed

Overview

The published Revenue contract does not define a general webhook subscription surface. Preserve this public route by implementing provider-supported polling: direct paginated audit reads for administrative changes or asynchronous activity exports for emails, meetings, and files.

Prerequisites

• Chosen feed type, organization scope, and authorized fields
• Monotonic time window or pagination checkpoint with overlap policy
• Deduplication store and downstream event schema

Instructions

Step 1: Choose the supported source

Use GET /audit/events for paginated audit changes or POST /export/activity plus the export-job lifecycle for activity data.

Step 2: Freeze the window

Record inclusive and exclusive boundaries, page limit, overlap allowance, timezone, and the first checkpoint before requesting data.

Step 3: Read or queue

Page audit events in stable order, or queue one activity export and persist its job ID before polling.

Step 4: Normalize event identity

Derive a deterministic key from provider identifiers, event type, actor, timestamp, and source window; retain the source job or page lineage.

Step 5: Deduplicate and advance

Publish only validated unseen events, then advance the checkpoint atomically after the downstream sink acknowledges the batch.

Step 6: Detect gaps and replay

Monitor lag, empty windows, page discontinuity, aborted jobs, and reconciliation counts; replay from the last safe checkpoint within retention.

Authentication

Use the Revenue apikey header and an identity authorized for the selected audit or activity data. Do not log actor identities, email content, meeting details, filenames, or the token in event-processing telemetry.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Feed definition and checkpoint policy
• Normalized event batches with provider lineage and deterministic keys
• Lag, gap, deduplication, replay, and checkpoint receipts

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

An audit feed polls with a small overlap, deduplicates by provider event identity, publishes a validated batch, and advances its cursor only after the sink acknowledges it. No unsupported webhook registration is attem…