What to establish before an integration project starts

Integration projects often begin after someone has already decided that two products should talk to each other. An interface exists, a vendor can write the connector, and the remaining work looks like moving records from one place to another. That is how a project can start with a technical brief and still leave the organisation unsure, months later, which system staff should trust when the two records disagree.

Getting the connector to work is part of the job. The harder part is agreeing what should happen between the systems: which one is allowed to change a fact, what event should start that change, what staff should do when a transfer stops halfway, and who is responsible once the connection is part of ordinary work. This Guide is about establishing those things before implementation starts, so the connector is built around an agreed process rather than around whatever the first available interface happens to expose.

A request that succeeds in a test environment does not tell you whether the same transfer will be noticed if it fails on a Tuesday, who will repair it, or how staff will know which record is correct. Settling those questions first is cheaper than discovering them after the integration is already in use.

The process that actually runs

A diagram of two applications is easy to draw. The work that happens today is often longer than that diagram. Someone may enter a customer in one system, copy a reference into another, wait for an email approval, then update a status by hand. A spreadsheet may be the only place an exception is recorded. If the project starts from the diagram, it will connect the two products and leave the people, the spreadsheet and the approval sitting outside the new path, still doing the work the integration was supposed to absorb.

The first thing to establish is the current process as it actually runs, not as a procedure says it should run. Who starts it? What information do they need, and where is that information already stored? What has to be true before the next step can happen? What do people do when the usual path does not fit? Those answers tell you what the integration has to preserve. They often show that the technical connection is only one piece of a longer sequence.

Ordinary cases make this concrete without inventing a client story. A new customer might be created in a CRM and then typed again into a finance system so an invoice can be raised. An enrolment might become active in one product while membership status is still waiting for someone to tick a box in another. A payment might clear in the banking product while the invoice in the practice system still shows unpaid until someone notices. The integration that creates the customer, or marks the invoice paid, only helps if it is attached to those real steps, including the exceptions.

Automation sits around that process rather than instead of it. If a later step should happen automatically once the information has arrived, that decision still depends on knowing the process, the owner of each fact, and what staff should do when the automatic step does not run. It is not a separate product category to settle before the process is understood.

Which system is allowed to define each fact

Once the process is visible, the next question is authority. Several systems may hold a copy of the same customer, the same invoice, or the same membership status. That is normal. Trouble starts when two of them are allowed to change the same fact without an agreed rule about which change wins.

For each important piece of information, the organisation needs to name which system is allowed to define it. That system is the source of truth: the place staff should treat as correct when copies disagree, and the place other systems should take their updates from. Contact details might belong in the CRM. Invoice status might belong in the finance system. Payment status might belong with the payment product. Enrolment or membership might belong in the system that actually records whether someone is current. Workflow status, such as approved or cancelled, often belongs in the system where the work is done, not in every product that happens to display a flag.

Ownership does not have to sit in one application for every field. One system can own the customer's identity while another owns their billing terms. The requirement is that the split is explicit. If both systems can edit the phone number, the next change in either place will overwrite the other, and staff will start keeping a third copy they trust more than either product. Integration then becomes conflict resolution: deciding, after the fact, which update was meant to count.

Before anyone writes the connection, the organisation should be able to say which system creates the record, which one is allowed to correct it, and what happens if the record is deleted on one side. Without those answers, copying in both directions will look helpful and then quietly produce duplicates, stale copies and circular updates.

When and how information should move

It is easy to assume that if two systems both hold a record, they should keep each other updated in both directions. That sounds complete. It is also how an organisation ends up with two masters and no way to tell which change was intended.

A simpler rule is usually safer. One system changes the fact; the other receives the result. If a correction needs to travel back, that is a separate decision with its own owner, not a default. Deletes need the same care. Removing a customer from a marketing list is not the same as removing them from the system that still has invoices. Duplicates appear when both sides can create the same record without a shared identifier. Stale information appears when a copy is updated locally and nobody has said that local edit does not count.

Two-way copying is sometimes required. It is more work, not a mark of a more complete design. It needs a conflict rule, a matching rule, and someone who can explain what staff should do when both sides have been edited. If those cannot be stated, the organisation is not ready to copy in both directions.

The transfer also needs a starting point that matches the process. The event that should cause information to move is a business event: a customer is accepted, an enrolment becomes active, an invoice is paid, a booking changes, a status is approved, a record is cancelled. The product may offer a different event, or only a scheduled export, or only a file that someone downloads. Starting from the product's event list is how a project copies data at the wrong moment, copies it every time a field is touched, or misses the step that actually matters.

Ryoss starts with the process, then looks at what the products can emit or accept. If the product cannot tell you when an enrolment became active, and can only dump a list of records each night, the design has to live with that delay, or the process has to change, or a person still has to confirm the step. Treating the product's available event as if it were the business event hides that constraint until staff notice records arriving too early or too late.

When a transfer fails

A transfer can stop for ordinary reasons: one system accepts a change and the other rejects it because a required field is missing, a request times out, credentials expire, or the other product is simply unavailable. Records also fail to match when the two sides never shared a stable identifier, and a retry can create a duplicate if the first attempt actually succeeded and nobody could see that.

Those cases are normal enough that they should be designed for. The organisation needs to know whether anyone is told, whether the same request can be sent again without making the problem worse, and whether someone can repair the item without guessing which system is correct. If the only evidence of success is a green response during development, staff will spend the following year checking both products by hand.

Retries need a rule. Sending the same payment instruction twice is not the same as sending a customer update twice. Some operations can be repeated safely; others create a second invoice or a second membership. If that distinction is not made before go-live, people will be afraid to replay a failure, and the failed items will sit there.

Matching is part of the same problem. If the integration cannot say that this record in one system is that record in the other, a failure cannot be repaired cleanly and a duplicate cannot be recognised. Stable identifiers, agreed before the first transfer, are how later recovery stays possible.

Visibility belongs with the people who run the process, not only with the person who built the connector. Someone has to be told, or be able to look, when yesterday's transfers did not complete. Otherwise the integration fails silently and the first the organisation hears is a customer, a finance discrepancy, or a staff member who has stopped trusting either system.

Even when the usual path is working, copies drift. A person edits a field that was supposed to be read-only. A vendor change stops one type of update. A weekend outage is retried incompletely. A successful response from the interface means the other system accepted a request. It does not always mean the business process finished. The invoice may be marked paid in one product while the membership that payment was meant to activate is still pending in another.

Reconciliation is the ordinary work of comparing the two sides and finding the differences: records that did not transfer, records that disagree, records that exist in only one system, and failures from yesterday that were never resolved. It does not have to be elaborate. It does have to exist for anything the organisation would be embarrassed to get wrong, and someone has to own the exceptions it produces. Using reconciliation to paper over a workflow that fails every day is a different problem; that workflow still needs to be fixed.

Expecting the connector never to fail is the wrong target. The organisation needs a failure to be visible, to be retried or repaired without making the data worse, and to be shown as resolved afterwards. That is the operational design the connector has to support.

What the products will actually allow

The design is limited by what the systems can do, not by what the project wished they could do. One product may offer a documented interface; another may only export a file. Some vendors require approval before an integration can go live. Authentication may be possible for a test environment and awkward in production. Historical records may be available, or only new records from the day the connection starts. The vendor may change the interface and tell customers afterwards. Usage limits may make a chatty design expensive or unreliable. Licensing may forbid the very connection the project assumed.

These constraints change what the integration can honestly promise. If the product cannot emit the business event you need, you cannot design as if it can. If there is no test environment, you will learn the failure cases in production unless you find another way to practise them. If the vendor can change the interface without notice, someone has to be responsible for noticing and adapting. Establishing the constraint is part of deciding whether to proceed, not a surprise for the last week of the project.

Who owns it after it is live

The person or firm that builds the connector is not automatically the owner of the result. Once the integration is part of operations, someone has to watch it, renew credentials, respond when the vendor changes their product, repair failures, run or review reconciliation, and decide whether the connection still matches the process. Those jobs may sit with the person who owns the business process, the person who owns one of the systems, an internal technology team, an external vendor, or whoever maintains the integration. Organisations name those roles differently. The work still has to land somewhere named.

If it does not, the original developer becomes the default owner by accident, including after they have left. Each vendor may assume the other side will notice a failure. Staff invent a spreadsheet because that is the only way they can tell whether yesterday completed. The commercial cost of that arrangement is not dramatic. It is the permanent extra checking, the disputed invoice when records do not match, and the difficulty of changing either product later because nobody can describe what the connection actually does.

Ryoss treats integration as an operational system: something that has to fail visibly, be repaired, and remain understood after the project team has moved on. That is why ownership after launch belongs in the same conversation as the first mapping of fields.

What has to have been seen to work

Before go-live, the organisation should have watched more than a clean record travelling from one system to the other. It should have seen what happens when a required field is missing, when the same record arrives twice, when the other system is unavailable, when a retry is safe and when it is not, when a record is changed after the first transfer, when a record is cancelled or deleted, and how a failed item is found and repaired. It should have seen a comparison of the two sides that can list yesterday's exceptions.

A clean transfer shows that the connector can run. The organisation still needs to have watched a failure being found and repaired, because that is the path it will live with after go-live. If those cases have not been exercised, go-live is the first time the operational design will be tested.

Before implementation starts

The organisation is ready to start building when it can explain, in ordinary language, the things the connector will have to honour:

• the process as it runs today, including the exceptions
• which system owns each important fact
• which way a change is allowed to travel
• what event should cause a transfer
• what staff and systems should do when a transfer fails
• how the two sides will be compared later
• who is responsible once it is live
• which vendor or platform limits the design
• which failure and recovery cases will be walked through before go-live

If those answers are still being deferred to the implementer, the project is still in investigation. That investigation is the work that stops an integration from becoming another manual process with a connector attached.