Subscription Provider Field Map

Implementation model

Build the connection as an operating system, not a one-off script.

Each connector needs admin ownership, database mapping, failure handling, and a client-safe proof story before it becomes part of the portal.

Provider

Start with a named provider

Subscription provider object should have a provider key, connection status, owner, and clear reason for being connected.

Runtime

Choose the runtime boundary

Field maps should preserve source context while keeping portal labels simple.

Owner

Assign a human owner

Data owner owns setup, verification, incident response, and the client-facing summary.

Mapping

Normalize before reporting

Provider fields should be mapped into ZartsAlgo records before reports, portal cards, or automations depend on them.

Proof

Show client-safe movement

The portal should show source, baseline, current value, status, and next action without exposing raw payloads.

Recovery

Plan rollback and retries

Every connector needs retry rules, dead-letter handling, and a manual fallback for important client updates.

Tables

Primary tables involved.

These are the first tables to check when implementation moves from planning to MySQL-backed code.

integration_field_mappings
integration_external_objects
integration_object_links
data_import_rows
data_import_batches

Checklist

Steps before this is live.

Create or confirm the integration provider record.
Create a connection record with client, provider account ID, environment, and status.
Document auth type, scopes, credential storage, refresh needs, and revocation path.
Add sync job or webhook event names before processing live data.
Map external object types to internal tables and fields.
Run a small test batch and record records seen, created, updated, and failed.
Create a baseline before the connector changes reports or automations.
Define what the client is allowed to see in the portal.
Add monitoring for stale syncs, rate limits, failed webhooks, and duplicate events.
Keep a manual import path until the connector has proven reliability.

Client proof

Signals this can safely feed.

Metrics should become report notes, portal cards, admin tasks, or incident alerts. Raw provider data stays internal.

Metric

mapped fields

Track this signal only when source, period, unit, and client meaning are clear.

Metric

required fields

Track this signal only when source, period, unit, and client meaning are clear.

Metric

validation errors

Track this signal only when source, period, unit, and client meaning are clear.

Metric

ignored fields

Track this signal only when source, period, unit, and client meaning are clear.

Timeline

Implementation checkpoints.

Access

Access checkpoint

Confirm account access, provider docs, auth model, and required scopes.

Connection

Connection checkpoint

Create provider and connection records, then store credentials outside public code.

Mapping

Mapping checkpoint

Map objects, fields, statuses, and metric names into ZartsAlgo tables.

Test

Test checkpoint

Run a test sync or webhook and review created, updated, failed, duplicate, and ignored records.

Report

Report checkpoint

Create the client-safe baseline/current explanation and the next action.

Monitor

Monitor checkpoint

Watch stale syncs, rate limits, errors, and portal visibility after launch.

Avoid

Things that break trust.

Do not store provider tokens in public PHP files or in readable JSON records.
Do not merge different lead sources without source labels.
Do not overwrite a baseline with a partial sync.
Do not show raw accounting, CRM, phone, or marketplace payloads to clients.
Do not treat webhook delivery as proof that the normalized record was created.
Do not give the runtime app user schema-changing privileges.
Do not launch without an owner, last-tested date, and failure path.
Do not let provider-specific language leak into generic client reports.