Il contratto dati dell'integrazione

Disponibile anche in 19 lingue

English · Español · 日本語 · Português (Brasil) · Français · Deutsch · 한국어 · 简体中文 · Português (Portugal) · 繁體中文 · Bahasa Indonesia · Türkçe · Polski · Tiếng Việt · ไทย · Українська · Español (México) · Français (Canada) · Deutsch (Schweiz)

A locomotive and a freight car a foot apart on the same track, their couplers lined up and the brake hoses hanging below. — Immagine generata con l'IA

Modulo 4 di 4 del capitolo Integrazione e movimento dei dati, capitolo 9 del corso Data Architect. Ogni modulo si regge da solo. Previous: Proof of Delivery · Next: the next chapter, Migration and Synchronization ⟲

La domanda a cui risponde questo modulo: Come metti per iscritto cosa può fare ogni integrazione ai dati?

By now we’ve asked a lot of questions about an arrow: who starts it, which way the data moves, how current, how much, what key, who owns each field, which pattern, which mechanism, who proves it arrived. Those decisions shouldn’t live only in the architect’s head, or scattered across a diagram, a story in the backlog, an API spec, a spreadsheet, three chat threads and the memory of whoever built it. I want a small architectural contract for every important arrow: the integration data contract. ⟲

Every Important Arrow Gets a Contract

Here’s Steve Trucking’s landscape one more time, in the same places as module 1. In chapter 4 we learned to see the arrows. In this chapter we’ve learned to ask what each one means. Now give each important arrow a number. ⟲

Clicca per ingrandire

The landscape is the index. Each number opens a contract. ⟲

Nine arrows, nine contracts. Notice that every partner has two: manifests in and status out are different integrations, with different initiators, timing, keys, fields and failure handling. A double-headed arrow labeled “partner sync” would hide all of that. I’d rather have two clear contracts than one vague “bidirectional” one. ⟲

Una freccia ha bisogno di più di un’etichetta

A label like “Account Sync” says almost nothing. Does the ERP send or does Salesforce ask? Hourly, nightly, as it happens? Ten accounts a day or ten million? Matched by Salesforce ID, customer number or name? Which fields may the ERP change? What if record 4,291 fails? The label hides every one of those decisions. The contract exposes them. ⟲

The first lines are module 1’s questions, now written down as decisions. Then two lines the integration architect fills in, and two that Salesforce’s own Well-Architected guidance adds: ⟲

Line	The decision
Iniziatore	Chi avvia la conversazione?
Direzione dei dati	In che direzione si muovono i dati di business?
Freshness	How current must the data be, in a number?
Volume e forma	Quanti, e come singoli, insiemi o massa?
Chiave	Come identifichiamo lo stesso record tra sistemi diversi?
Write authority	Which system owns, and may write, which fields?
Pattern	Request and reply, fire and forget, batch, or events?
Meccanismo	Cosa lo implementa?
Proof of delivery	Who proves it arrived, and owns recovery?
Sensitivity and travel	How sensitive is the data, and where does it pass through?
Change	How does the contract change without breaking the other side?

It extends chapter 4’s landscape inventory, one row per arrow. It isn’t an API specification: endpoints, payloads, schemas, authentication and response codes all matter, later. First I want to know what the integration is supposed to mean to the enterprise’s data. ⟲

The last two lines come straight from Salesforce’s framework. Its data protection guidance expects “data classification preserved across system boundaries” and “data transit paths evaluated for residency compliance, not just storage location”; one of its anti-patterns is integration middleware running in a region outside the compliance boundary (Data Protection Patterns (si apre in una nuova scheda)). And for events it says “event schemas become contracts between producers and consumers”: add new fields rather than changing existing ones, and version explicitly when a breaking change can’t be avoided (Operational Excellence (si apre in una nuova scheda); both checked 2026-10-27). ⟲

Contract C1: Redrock’s Manifests

Now zoom in on C1. In module 1 we asked Redrock’s arrow seven questions. Here are the answers as a contract, and next to each line, how we’ll know it’s true. ⟲

Clicca per ingrandire

Contract C1. A line is only finished when you can check it. ⟲

Notice two things. First, we made nearly every data decision before choosing the technology. The mechanism line says “the integration architect’s choice, to fit the lines above,” and that’s healthy: what, why, who, how much, how current, whose value, who proves it arrived. Then the integration architect picks the mechanism that satisfies the contract. ⟲

Second, look at the right-hand column. Every line has a test. “A revision is on the Work Order within 15 minutes” can be measured every day. “Sent equals accepted plus rejected” can be checked every evening. A contract line you can’t check is a hope, not a requirement. ⟲

Requirements, Then Pattern, Then Mechanism

When I teach integration, I give people the order to think in. First the requirements: the direction of action, who starts it, which can be different from the way the data flows; the source and the target; the timing, real time, near real time or batch; and the volume. Then the pattern: fire and forget, request and reply, batch data synchronization, virtualization, remote call-in, an update to the user interface when data changes. Then the mechanism. And there are only so many ways in and out of Salesforce: the REST, SOAP, Bulk, Streaming and Pub/Sub APIs, platform events, Change Data Capture, outbound messaging, callouts from Apex, Flow or External Services, Salesforce Connect, Heroku Connect. Those are the doors. Pick one only once you know what has to walk through it. ⟲

Here’s C1 walked through that order. ⟲

Clicca per ingrandire

Requirement, pattern, mechanism. Every option set aside has a reason you can say out loud. ⟲

The two get collapsed all the time. “We’re using REST” doesn’t tell me the architecture: who calls whom, when, how often, how much, what happens on failure. REST is a mechanism; the contract gives it meaning. And don’t let the mechanism become the requirement. “We need a REST integration” is probably not the requirement. “When a delivery is revised, the coordinator sees it on the Work Order within 15 minutes” is. Now we can architect: maybe REST, maybe events, maybe the integration platform already does it, maybe Salesforce should fetch the value instead of storing it. Requirement, pattern, mechanism. Start at the mechanism and you skipped the architecture. ⟲

And build for more than what’s asked. Every integration has implied requirements nobody writes down: errors will happen, volumes will grow, the business will add a second flow next year. Plan for three years, not just go-live. The contract is where those implied requirements become explicit. ⟲

Test knowledge. Separate the pattern (how the systems interact) from the mechanism (what implements it). Expect a scenario that describes requirements (who starts it, which way the data moves, how fast, how much) and asks for the pattern or the Salesforce mechanism that fits: for example, near real time from Salesforce without waiting for an answer points to platform events; millions of records points to the Bulk API. ⟲

A Contract Between Teams

The contract isn’t only between systems. It’s between teams. On one project, the middleware team built the integrations into Salesforce, and we had a decision to make in the first week or two: would they call Salesforce’s standard REST API, or a custom API we built for them? ⟲

With the standard API, the middleware team has to know Salesforce deeply: your objects, your fields, your picklist values, the order the records have to be written in, and what each error means. They call the standard APIs, and they handle the issues. ⟲

Clicca per ingrandire

The standard API: the middleware team works with your objects and fields directly. ⟲

Add a custom object, rename a field, change a picklist value, and the integration breaks unless they’re in your meetings and quick to change their side. ⟲

Clicca per ingrandire

A release renames a field, and the integration breaks. ⟲

The other answer is a wrapper. In Salesforce that’s usually Apex: a class exposed as a REST resource, so external applications can call your code instead of your objects (Introduction to Apex REST (si apre in una nuova scheda), Apex Developer Guide, Winter ‘27, API version 68.0, checked 2026-10-27). Now you write your own REST contract, and the middleware team gets a single endpoint. Three things come with it: ⟲

Your own logging. You don’t depend only on the standard logs. Every incoming call can be timestamped and its payload recorded, so you can see exactly what arrived and replay it (module 3’s integration log). ⟲
Your own orchestration. One call can write the Work Order, its items and its status in the right order, inside Salesforce, instead of the middleware team making five calls and handling every partial failure. ⟲
A stable door. Rename a field, add an object, change a picklist value: you change the code behind the endpoint, and the contract stays the same. ⟲

The cost is real. It’s code, so it has to be built, tested and maintained by good Apex developers on the Salesforce side, and it still runs inside Salesforce’s limits: Salesforce’s guide says calls to Apex REST classes count against the org’s API limits and all standard Apex governor limits apply. Your team now owns part of the integration. ⟲

Clicca per ingrandire

A custom Apex REST endpoint: Salesforce owns a smaller contract, logs every call, and the rename stays inside. We chose the custom contract on more than one project, because there was a lot of internal processing to hide. ⟲

So the question for the first week or two is about people as much as technology: will the external team know Salesforce deeply, and be quick to change when your data model changes? Or do you put a wrapper in front, and own it? Either answer can be right. What isn’t right is not deciding. ⟲

Test knowledge. Know when to expose a custom Apex REST endpoint instead of letting the other system call the standard APIs: to give an external team one stable interface, to orchestrate several writes inside Salesforce, or to log every call yourself. Know the cost too: code to maintain, and the org’s API and Apex governor limits still apply. Write it into the contract: which interface, who owns it, and who has to be told when something changes. That’s what the change line is for. ⟲

Rendi specifica ogni riga

Volume: not “high.” High to one team is 10,000 a day, to another 100 million. Put numbers in: 1,100 deliveries a day, a set per distribution center each evening, 30% growth a year. Those numbers don’t only pick the mechanism; they shape storage, automation, locking, sharing, indexes, archiving, monitoring and retention. The contract connects integration volume back to data architecture. ⟲

Freshness: not “real time.” Write “a revision is on the Work Order within 15 minutes,” or “the partner’s manifest is in Salesforce at least a day before its delivery date,” or “finance reconciliation finishes each night before reporting starts.” Now it’s testable. “Real time” is an adjective; “within 15 minutes” is a requirement. ⟲

Key: not buried in the field mapping. Write the key field, whether it’s unique, who assigns it, and whether the relationship is really one-to-one. If one business thing has several external records, name the design: add records, not fields, as a hierarchy, peers or a child object (module 2 and chapter 6). Keys shouldn’t be an implementation surprise. ⟲

Write authority: maybe the most important data line. Not “objects: Work Order,” but “Redrock may write the items, the address and the delivery date; Salesforce owns the appointment, the crew and the route.” Now the integration can be tested against the authority model. If someone later adds the crew to Redrock’s payload, the contract asks: why? It becomes a governance control. ⟲

“But the integration user can edit it.” I don’t care. An integration user may have broad permissions because the implementation needs them; that doesn’t mean every integration using that identity should write every field it can. Permission says can; architecture says should. Good systems need both. And reading everything has a performance side too: Salesforce’s own case study of a slow integration user is in chapter 8 (When It’s Slow). ⟲

Proof of delivery: not “IT.” Name the side that knows what should arrive, and so proves it did (module 3). For C1 that’s Redrock, from Salesforce’s per-record results. For C2, status out, it’s Salesforce, with return receipts. For a scheduled pull, it’s the client that asks. The contract makes it explicit for each arrow. ⟲

Sensitivity and travel: not “secure.” Say what’s in the payload and how sensitive it is (C1 carries Recipient names, addresses and phone numbers), and every place it passes through: the integration layer, its logs, its retry queue. Data that must stay in a country has to travel there too. ⟲

Clicca per ingrandire

Every place the data rests is a copy with a location. Count the logs and the queues. ⟲

Change: not “we’ll coordinate.” Say how the contract evolves: new fields are added, never renamed; a breaking change gets a new version; the other side gets notice. A contract that can’t change safely will be broken quietly instead. ⟲

The Contract Isn’t the Mapping

The implementation will have a field mapping too: Redrock’s field A to Salesforce field B, transformations, types, defaults. Useful. The contract sits a level above it: why the data moves, who owns it, how current, how much, how identified, who may change it, how the interaction is shaped, who proves it arrived. It gives the mapping its context. ⟲

Più org, e “non spostarlo”

The landscape holds Salesforce North America, Salesforce Europe and an acquired company’s org. Maybe we’re consolidating, syncing selected records, keeping some data local, or building a common customer or analytics layer. Don’t start with “how do we sync three orgs?” Start with the contracts. For each movement: what data, which direction, which org is authoritative, what’s the enterprise key, how current, what volume, why copy it, who may write it, who proves it arrived? That every box has a Salesforce logo doesn’t simplify the data questions. They’re still separate systems. Chapter 14 covers the multi-org patterns. ⟲

And sometimes the right contract says don’t move it. A large external dataset needed only occasionally, authoritative elsewhere, expensive to copy, changing constantly, mostly viewed? Why sync another copy? Virtualization may be better (Part 3). The contract forces that conversation because it asks why the copy exists. Remember FleetLink in module 1: C8 carries only the latest position, because the contract asked why 73 million readings a year would be copied at all. ⟲

The contract should also outlive the technology. ⟲

Clicca per ingrandire

At go-live: Middleware A, and contract C1. ⟲

Replace the middleware in three years, and Redrock still owns the items, the coordinator still needs revisions within 15 minutes, the key is the same, the volume is known, proof of delivery still matters. ⟲

Clicca per ingrandire

Three years later: new middleware, the same contract. ⟲

The mechanism changes; the contract mostly survives. That’s the sign you separated architecture from implementation. ⟲

The Other Eight Contracts

We could fill in C2 to C9 now: status back to each partner, Keystone’s files, Brightwave’s EDI, FleetLink, Snowflake, the finance ERP. I’m deliberately leaving them for Checkpoint 2, where we take the Part 1 landscape and apply every design chapter of Part 2 to it. For now, you have the tool, and one finished example. ⟲

Beyond the exam: what AI changes. Don’t document an agent as “the agent has tools.” Each important action is an integration contract: which system it calls, what key identifies the record, what it may read and write, who owns those fields, the expected volume, what happens on retry or partial failure, what evidence is kept, how sensitive the data is and where it goes. A probabilistic caller is invoking deterministic enterprise operations, so keep identity, write authority, failure handling and observability outside the model’s discretion. ⟲

Il contratto diventa uno strumento di revisione

Once every important arrow has a contract, a review stops being “does the diagram look right?” and becomes: do we know the initiator and the data direction, is freshness measurable, do we know the zeros, is there a stable key, is authority explicit, does the pattern fit the requirement and the mechanism fit the pattern, who proves it arrived, where does the data travel, how will it change? If the answer to one is “we haven’t decided,” good: you found architecture work before production found it for you. ⟲

Cosa decide qui un architetto

Which integrations are significant enough to need an explicit contract, and their numbers on the landscape. ⟲
The initiator, data direction, measurable freshness and Number of Zeros for each, before choosing technology. ⟲
La chiave tra sistemi e l’autorità di scrittura a livello di campo che preservano identità e gestione dei dati master.
The pattern, the mechanism and who proves delivery for each direction. ⟲
How sensitive the data is, where it travels, and how the contract changes without breaking the other side. ⟲
Se i dati debbano muoversi del tutto, e se il contratto sopravvive a un cambio di tecnologia.

A landscape simplifies complexity, which is useful, until an arrow hides the decisions that keep the data trustworthy. So draw the arrow, number it, then give it a contract you can check. Now it means something, and when the implementation changes, the architecture doesn’t disappear with it. That’s the difference between documenting an integration and designing the movement of enterprise data. ⟲

Per approfondire

Salesforce Architects, Data Integration with Salesforce (si apre in una nuova scheda) and Integration Patterns (si apre in una nuova scheda), checked 2026-11-01. ⟲
Apex Developer Guide, Introduction to Apex REST (si apre in una nuova scheda), Winter ‘27 (API version 68.0), checked 2026-11-01. ⟲
Salesforce Architects, Well-Architected, Data Protection Patterns (si apre in una nuova scheda) and Operational Excellence (si apre in una nuova scheda), checked 2026-11-01. ⟲
Il corso Integration Architect: I requisiti, I pattern di integrazione e Multi-org (coming soon).