ERP order sync: operations runbook

1. Overview

A nightly CSV export from the ERP (orders_YYYY-MM-DD.csv, dropped to SFTP at 01:30 UTC) is validated, matched on external_order_id and upserted into the CRM as order records associated with the company. Rows that fail validation are quarantined and listed in the exception report; nothing is written partially.

• Owner on your side: the operations lead named in the SOW.
• Runs: daily at 02:00 UTC, plus manual replays.
• Source of truth: the ERP for orders; the CRM for owners and stages.

2. Architecture

ERP ──(CSV over SFTP)──▶ ingest job ──▶ validate ──▶ upsert ──▶ CRM
                                  │                          │
                                  └──▶ quarantine table ◀────┘
                                             │
                                             └──▶ exception report + alert

The job runs as a scheduled function in your cloud account. State (last processed file, quarantine rows, run history) lives in a small Postgres database in the same account.

3. Environments and access

4. Deploying a change

1. Open a pull request. CI runs the schema tests and a dry run against the sample file.
2. Merge to main. The pipeline deploys to staging and replays yesterday’s file.
3. Check the staging exception report matches production’s for the same file.
4. Promote to production from the pipeline. Rollback is the previous release, one click.

5. Monitoring and alerts

• File missing by 03:00 UTC: alert to the operations channel.
• Run failed (any unhandled error): alert, and the batch is left unapplied.
• Quarantine above threshold (more than 1% of rows): alert with the report attached.
• API rate limit reached: the job backs off and retries; alert after three attempts.

6. Procedures

Reprocess a failed batch

1. Fix the cause (bad file, expired credential, CRM outage).
2. Run replay --file orders_YYYY-MM-DD.csv from the pipeline.
3. Upserts are idempotent: replaying a file that partly succeeded cannot duplicate records.

Resolve quarantined rows

1. Open the exception report for the run; each row lists its reason.
2. Correct the data at the source (the ERP), not in the CRM.
3. The next nightly run picks the corrected rows up automatically.

Add a field

1. Create the property in the CRM sandbox, then in production.
2. Add the column to mapping.ts and its rule to the schema.
3. Deploy as above. Backfill with a replay of the files you need.

Rotate credentials

1. Create the new token in the CRM or SFTP server.
2. Update it in the secret manager; the next run uses it.
3. Revoke the old token and note the date in the change log.

7. Change log