Overview
Set the purpose, scope, audience, and boundaries before the detailed chapters.
4.8
on G2
Free Downloadable Template
Developer guide to connect systems: auth, workflows, data mapping, events, errors, testing, and go-live. Download the editable blank, or create a draft from your recordings in Docsie.
Use this guide to connect systems, verify data exchange, and operate the integration. Keep environment details and interface contracts explicit so an integrator can distinguish setup tasks from ongoing synchronization behavior.
Complete the bracketed fields with approved information for the product, organization, or program being documented. Repeat the named forms where several tasks or subjects need separate records. Remove sections that do not apply and retain links to the material used to complete the document.
| Document control | Entry |
|---|---|
| Document identifier | [Identifier used by your team] |
| Scope and applicable version | [Product, program, locations, and version covered] |
| Prepared and maintained by | [Responsible role or team] |
| Revision and review | [Revision, review date, and approval reference] |
Describe the business outcome and the system boundary before the technical workflow. Show the direction in which data and events move.
| Field | Complete with |
|---|---|
| Integration purpose | [Supported use cases, audience, and scope] |
| Systems and versions | [Source, target, supported editions or versions, and ownership] |
| Flow and pattern | [Direction, transport, synchronization or event pattern, and diagram reference] |
| Boundaries | [Data or capabilities excluded from this integration and related dependencies] |
Provide a short setup path to a first verified exchange. Separate sandbox and production values so test configuration cannot be mistaken for a production endpoint.
| Field | Complete with |
|---|---|
| Prerequisites | [Accounts, permissions, tools, source data, and connectivity] |
| Environment reference | [Environment, base URL, purpose, and access requirements] |
| First exchange | [Minimal request or connection task and expected result] |
| Readiness evidence | [Checks, observed responses, and unresolved setup issues] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Document each credential or trust relationship by its purpose. Keep live credential values outside the document and record the access mechanism used to obtain them.
| Field | Complete with |
|---|---|
| Method | [Authentication scheme, supported clients, and trust relationship] |
| Credential lifecycle | [Obtain, refresh, rotate, expire, and revoke procedures or references] |
| Permissions | [Required scope, role, resource boundary, and approval route] |
| Verification | [Successful and denied access checks and relevant error responses] |
Create one workflow per task or use case. Identify state and ownership at every handoff and link each operation to its reference definition.
| Field | Complete with |
|---|---|
| Workflow goal | [Trigger, starting state, participants, and desired outcome] |
| Sequence | [Operations, dependencies, transformations, and decision points] |
| Data state | [Identifiers, checkpoints, reconciliation state, and completion evidence] |
| Failure handling | [Partial completion, duplicate processing, recovery, and escalation] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Keep each operation or channel defined once. Preserve exact request and response names and link to the schemas and mappings used by the workflow.
| Field | Complete with |
|---|---|
| Operation or channel | [Method and path, message topic, or operation name] |
| Input contract | [Fields, types, constraints, required values, and schema reference] |
| Output contract | [Response or acknowledgment, statuses, fields, and interpretation] |
| Limits and access | [Permissions, rate or size limits, and authoritative source] |
Complete one mapping record for each object or message family. Describe how identifiers and values are translated and how unmapped or invalid data is handled.
| Field | Complete with |
|---|---|
| Object and direction | [Source entity, target entity, schema versions, and flow direction] |
| Field mapping | [Source field, target field, transformation, format, units, and allowed values] |
| Identity and integrity | [Identifier rules, uniqueness, relationships, and validation checks] |
| Exceptions | [Missing, invalid, duplicate, or unmapped values and the supported response] |
Separate subscription and verification tasks from the payload catalog. Record delivery behavior clearly enough to design safe client handling.
| Field | Complete with |
|---|---|
| Event catalog | [Event family, trigger, payload schema, and version] |
| Subscription | [Registration steps, callback requirements, and permissions] |
| Authenticity | [Verification method, source reference, and rejected-delivery handling] |
| Delivery semantics | [Retries, acknowledgment, ordering, duplicates, and reconciliation] |
Document the evidence an integrator needs to distinguish input, access, transport, and processing failures. Use the service's documented retry behavior.
| Field | Complete with |
|---|---|
| Error contract | [Exact code or status, message, diagnostic fields, and affected operation] |
| Limits | [Rate, size, timeout, or capacity limit with units and scope] |
| Recovery behavior | [Retry, backoff, idempotency, resumption, and partial-state handling] |
| Escalation record | [Timestamps, correlation identifiers, redacted evidence, and support route] |
Use representative test cases to check the complete exchange, including failure and recovery paths. Record the readiness decision separately from execution.
| Field | Complete with |
|---|---|
| Test coverage | [Use case, input, expected mapping, error path, and evidence] |
| Production readiness | [Access, configuration, monitoring, support, and reconciliation checks] |
| Cutover | [Sequence, responsible roles, decision points, and rollback criteria] |
| Acceptance | [Observed result, remaining issue, approver or acceptance reference, and handover] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Keep the reference material needed to maintain the integration after handover. Link recurring questions to the workflow or contract that answers them.
| Field | Complete with |
|---|---|
| Support | [Contact role or channel, severity rules, and escalation path] |
| Operational ownership | [Monitoring, reconciliation, change review, and incident responsibilities] |
| Change history | [Integration or schema change, affected workflow, and migration reference] |
| Glossary and questions | [Defined terms, common questions, and authoritative references] |
7 Repeatable Chapter Patterns
Teams preparing a integration guide from existing source material. Repeat a procedure, checklist, or reference chapter where needed, and keep only the sections your source material supports.
Set the purpose, scope, audience, and boundaries before the detailed chapters.
Give each task its prerequisites, ordered actions, expected result, and verification.
Keep exact settings, field values, commands, and supporting references easy to look up.
Connect an observable symptom to diagnostic checks, resolution, and verification.
Use repeatable checks for readiness, handover, or completion.
Group recurring questions with clear, source-supported answers and useful references.
Define the terms and abbreviations used throughout the document.
Use this guide to connect systems, verify data exchange, and operate the integration. Keep environment details and interface contracts explicit so an integrator can distinguish setup tasks from ongoing synchronization behavior.
Complete the bracketed fields with approved information for the product, organization, or program being documented. Repeat the named forms where several tasks or subjects need separate records. Remove sections that do not apply and retain links to the material used to complete the document.
| Document control | Entry |
|---|---|
| Document identifier | [Identifier used by your team] |
| Scope and applicable version | [Product, program, locations, and version covered] |
| Prepared and maintained by | [Responsible role or team] |
| Revision and review | [Revision, review date, and approval reference] |
Describe the business outcome and the system boundary before the technical workflow. Show the direction in which data and events move.
| Field | Complete with |
|---|---|
| Integration purpose | [Supported use cases, audience, and scope] |
| Systems and versions | [Source, target, supported editions or versions, and ownership] |
| Flow and pattern | [Direction, transport, synchronization or event pattern, and diagram reference] |
| Boundaries | [Data or capabilities excluded from this integration and related dependencies] |
Provide a short setup path to a first verified exchange. Separate sandbox and production values so test configuration cannot be mistaken for a production endpoint.
| Field | Complete with |
|---|---|
| Prerequisites | [Accounts, permissions, tools, source data, and connectivity] |
| Environment reference | [Environment, base URL, purpose, and access requirements] |
| First exchange | [Minimal request or connection task and expected result] |
| Readiness evidence | [Checks, observed responses, and unresolved setup issues] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Document each credential or trust relationship by its purpose. Keep live credential values outside the document and record the access mechanism used to obtain them.
| Field | Complete with |
|---|---|
| Method | [Authentication scheme, supported clients, and trust relationship] |
| Credential lifecycle | [Obtain, refresh, rotate, expire, and revoke procedures or references] |
| Permissions | [Required scope, role, resource boundary, and approval route] |
| Verification | [Successful and denied access checks and relevant error responses] |
Create one workflow per task or use case. Identify state and ownership at every handoff and link each operation to its reference definition.
| Field | Complete with |
|---|---|
| Workflow goal | [Trigger, starting state, participants, and desired outcome] |
| Sequence | [Operations, dependencies, transformations, and decision points] |
| Data state | [Identifiers, checkpoints, reconciliation state, and completion evidence] |
| Failure handling | [Partial completion, duplicate processing, recovery, and escalation] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Keep each operation or channel defined once. Preserve exact request and response names and link to the schemas and mappings used by the workflow.
| Field | Complete with |
|---|---|
| Operation or channel | [Method and path, message topic, or operation name] |
| Input contract | [Fields, types, constraints, required values, and schema reference] |
| Output contract | [Response or acknowledgment, statuses, fields, and interpretation] |
| Limits and access | [Permissions, rate or size limits, and authoritative source] |
Complete one mapping record for each object or message family. Describe how identifiers and values are translated and how unmapped or invalid data is handled.
| Field | Complete with |
|---|---|
| Object and direction | [Source entity, target entity, schema versions, and flow direction] |
| Field mapping | [Source field, target field, transformation, format, units, and allowed values] |
| Identity and integrity | [Identifier rules, uniqueness, relationships, and validation checks] |
| Exceptions | [Missing, invalid, duplicate, or unmapped values and the supported response] |
Separate subscription and verification tasks from the payload catalog. Record delivery behavior clearly enough to design safe client handling.
| Field | Complete with |
|---|---|
| Event catalog | [Event family, trigger, payload schema, and version] |
| Subscription | [Registration steps, callback requirements, and permissions] |
| Authenticity | [Verification method, source reference, and rejected-delivery handling] |
| Delivery semantics | [Retries, acknowledgment, ordering, duplicates, and reconciliation] |
Document the evidence an integrator needs to distinguish input, access, transport, and processing failures. Use the service's documented retry behavior.
| Field | Complete with |
|---|---|
| Error contract | [Exact code or status, message, diagnostic fields, and affected operation] |
| Limits | [Rate, size, timeout, or capacity limit with units and scope] |
| Recovery behavior | [Retry, backoff, idempotency, resumption, and partial-state handling] |
| Escalation record | [Timestamps, correlation identifiers, redacted evidence, and support route] |
Use representative test cases to check the complete exchange, including failure and recovery paths. Record the readiness decision separately from execution.
| Field | Complete with |
|---|---|
| Test coverage | [Use case, input, expected mapping, error path, and evidence] |
| Production readiness | [Access, configuration, monitoring, support, and reconciliation checks] |
| Cutover | [Sequence, responsible roles, decision points, and rollback criteria] |
| Acceptance | [Observed result, remaining issue, approver or acceptance reference, and handover] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Keep the reference material needed to maintain the integration after handover. Link recurring questions to the workflow or contract that answers them.
| Field | Complete with |
|---|---|
| Support | [Contact role or channel, severity rules, and escalation path] |
| Operational ownership | [Monitoring, reconciliation, change review, and incident responsibilities] |
| Change history | [Integration or schema change, affected workflow, and migration reference] |
| Glossary and questions | [Defined terms, common questions, and authoritative references] |
Bring your recordings and select this template. Docsie organizes supported material into chapters and task articles for your team to review.
Downloads are editable blank templates. Review generated content against your source material before use.
Install, configure, secure, monitor, back up, and maintain a system as its administrator
Software architecture description in arc42 order: goals, context, views, decisions, quality, and risks
Developer portal with quickstart, authentication, concepts, how-to guides, endpoint reference, errors, and changelog.