Integrations: defining reads and writes

Start with an operational decision

Start with the decision needing information and the subsequent action, not connector counts. Order lookup needs a source and fields; modification also needs permissions, rules and confirmation. Read access does not imply write capability. Document scope per process and system rather than calling partial access complete integration. Describe the visible outcome of each proposed connection in operational terms. Reading an order status, preparing an update and committing that update are three different capabilities with different failure conditions. Listing them separately helps stakeholders understand what the integration will actually support and what will remain a task for the team.

Identifiers that join records

Systems may use different customer names and order references. Define mappings and ambiguous-match handling; names or email addresses may be insufficient. Preserve original references for investigation. Authority may differ by field: contact ownership need not match delivery or availability ownership.

Plan for incomplete operations

Systems may respond late, reject requests or complete actions without notification. Distinguish outcomes before retrying. Unknown results require reference checks or review according to system capability. Blind retries can duplicate bookings or tasks. Preserve attempted, confirmed and uncertain steps during recovery. Recovery needs enough evidence to distinguish a rejected request from an unknown result. A timeout or missing notification alone may not establish whether the action occurred. The procedure should use the references and checking mechanisms available in the connected system, and stop for review when it cannot determine the state reliably.

Data and version changes

Renamed fields, catalogs and internal rules can change exchange meaning. Assign owners and dependency-change reviews. Test missing data, unknown references, delays and insufficient permissions, not only success. Operational records should support investigation without unnecessary sensitive copies. Failure categories guide data, rule or external-system fixes. Assign responsibility for changes on both sides of the connection. A catalog owner may alter the meaning of a category without changing its technical format, so a connection can continue operating while producing the wrong business interpretation. Include semantic changes in review conversations, not only technical failures. During the pilot, compare a sample of source records, transferred fields and final results to confirm that the intended meaning survives the exchange.

A simple agreement between teams

Document inputs, outputs, permissions, authoritative sources and recovery for each action. Validate with both systems’ operators to surface assumptions before confusing demonstration or production errors.

Illustrative example: checking an order and rescheduling its delivery

In a hypothetical case, an agent must report an order’s status and, where appropriate, change its delivery date. To report, it needs to read three fields from an order system: status, promised date and carrier. Reading requires a reliable identifier, so the design defines how the number the customer gives relates to the system record, and what happens if there are two matches.

To reschedule, the path is different. Permissions are verified, the change rule is checked, the customer is asked to confirm and only then is the write sent. If the system’s response is late or empty, the agent does not repeat the change: it checks whether the modification was recorded, and if it cannot know, it passes the case to a person with the operation reference. Reading and writing share a system but not their risks.

Channel design: what changes when the entry point is WhatsApp, voice or web

The channel determines which data arrives and in what quality. Over WhatsApp, the customer may paste an order number with typos, send a photo of a receipt or write several times. The integration must normalize the identifier, tolerate duplicates and accept an attachment without assuming it holds valid data until checked. On voice, dictated numbers need a read-back confirmation before anything is queried. On the web, the person may be authenticated and provide a more reliable identifier.

The cost of an error changes too. Data misheard on voice is caught with a repetition; in an asynchronous message, the customer may not see the correction for hours. Document per channel what is accepted as an identifier, what extra verification is requested and when to escalate. Check the current conditions of messaging and voice providers, since they influence the response times the design can promise.

Review checklist for an integration before turning it on

Before the first real conversation, review the integration with the people who operate each system, not only with whoever built it. Each question should have a written answer with an owner.

• Which system is the source of truth for each data point, and what happens if two systems disagree?
• What permissions does the connection have, and are they limited to the minimum needed?
• How is a failed operation told apart from a lost confirmation before retrying?
• Who is notified when a field, catalog or rule the exchange depends on changes?
• Were missing data, unknown references and delayed responses tested, and not just the successful case?