Integration project playbook
This page is for project leads at integration companies and for customers' project managers. It adapts the implementation project playbook of the partner section to projects whose main subject is the connection between systems. It is a playbook, not a method you must follow: adapt it to your contracts.
Contents
The phases
| Phase | Deliverables | Pages |
|---|---|---|
| 1. Discovery | Systems, data flows, directions, volumes, timing, owners, constraints; the discovery worksheet filled | Discovery worksheet, What integrators do |
| 2. Interface design | One interface specification per flow: surface, credential, mapping, keys, errors, monitoring | Interface specification template, Choosing an integration surface |
| 3. Estimate and agreement | Estimate with assumptions, statement of work, acceptance criteria | Estimating, Statements of work |
| 4. Environments and access | Development and staging installations from Git; test instances of the other systems; service accounts; credentials stored | Develop with Git, Service accounts |
| 5. Build | The integration extension: mapping, client, import or sender, hooks, cronjob parts, tests | Building an integration as an extension, Writing an import |
| 6. Test | Unit and contract tests in CI, dry runs on a copy, the idempotency test, end-to-end in staging, security review | Testing, Security checklist |
| 7. Go-live | Initial load, schedules on, monitoring on, rollback plan ready | Go-live checklist |
| 8. Hypercare | Two to four weeks of close watching; fixes; tuning of thresholds | Monitoring |
| 9. Handover | Runbook, credentials inventory, documentation, training of operators | Handover of an integration |
| 10. Operations | Upgrades, key rotation, reconciliation, changes of the other systems | Upgrades |
Roles on both sides
| Role | Integrator | Customer |
|---|---|---|
| Project lead | Plans, reports, manages scope | Decides priorities, signs acceptance |
| Integration architect | Designs flows and surfaces | Provides the landscape and constraints |
| Integration developer | Builds and tests the extension | |
| Owner of each other system | Provides test instances, credentials, API documentation, a contact who answers within a day | |
| Data owner | Decides master data, mapping and removal policies | |
| Operations | Prepares runbook and monitoring | Runs it after handover (or contracts it) |
| Security and data protection | Follows the security checklist | Approves data flows and processors |
The most common cause of delay is not code: it is waiting for access to the other system's test instance, its credentials or an answer about its data. Put those dates into the plan as customer deliverables.
Risks to manage
| Risk | Mitigation |
|---|---|
| The other system's API is undocumented or changes | Contract tests with recorded answers; a named contact; a change notice clause in the agreement |
| Data quality at the source is worse than assumed | Dry run on real data in discovery; a budget line for cleansing rules; a report of rejected records |
| Volumes are larger than assumed | Measure in discovery; design batch and delta from the start |
| No test instance of the other system | A test double for development; a short supervised window on production with read-only credentials |
| Editors change imported fields | Ownership of each field in the mapping; roles that prevent it; training |
| Key person dependency | Everything in the extension's repository and documentation; pairing |
| Silent failure after go-live | Monitoring with alerts before go-live, not after the first incident |
Rules of thumb
- Build the thinnest end-to-end flow first (one record, one field, all the way), then widen it.
- Agree the removal policy before the first import; it is the decision most often forgotten.
- Never go live on a Friday or before a holiday.
- Plan hypercare in the budget; it is when the thresholds are tuned.
- Keep the customer's own team involved; they will run it.
Related pages
- Implementation project playbook
- Planning an Exponential project
- Project templates
- Risk management
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.