The Building Nobody Described

Module 4 of 6 in the chapter Think Like an Integration Architect, chapter 1 of the Integration Architect course. Each module stands on its own. Previous: Every Arrow Is a Decision · Next: Owners, Boundaries and Change

The question this module answers: What does a client expect from an integration that they never ask for, and how does an architect find it before go-live?

Has this ever happened to you? You get to the end of a project. Everything you were asked for is built, tested and working. And the client looks at it and says, “Where is this?”

And you say, “You didn’t ask for that.”

And they say, “Well, I assumed you would have given that to me in the first place.”

Every class I ask that question, hands go up. Usually someone says it happened to them in the past week alone. It’s one of the most common ways a project goes wrong, and it’s almost never about a feature somebody forgot. It’s about a requirement nobody said out loud.

The Blueprint and the Trades

I like to compare integration architecture to construction, because there are so many parallels. When you put up a building, you have many trades: electricians, plumbers, the people pouring the foundation. They have to coordinate. If you lay the foundation and forget to put the pipes in the concrete, the plumber can’t run anything. That’s why someone holds the blueprint, and the blueprint shows every trade at once.

An integration project is the same. The Salesforce team, the team that owns the other system, the middleware team, security, the business: each one is a trade. The integration architect holds the blueprint that shows them all, and plans the places where their work meets before anyone starts building.

And the first thing on the blueprint isn’t the new building. It’s what’s already on the ground. What systems are there today? Which ones stay, and which ones go? Is Salesforce already in place, or is this a new installation? You can’t design an arrow between two systems until you know which systems you have.

Declared and Implied

Then come the business requirements, and there are two kinds.

Declared requirements are the ones the client tells you. Send the orders to the finance system. Show the customer’s latest delivery on the account. Load the history from the old system.

Implied requirements are the ones they expect without saying. And a lot of business requirements are implied. Our job, as architects, is to see those implied ones.

Think about the building again. If you build a commercial building, nobody hands you a requirement that says “the building must not burn down.” They expect it to be fireproof. They expect a fire alarm, emergency exits, the things every professional builder puts in because that’s what professional due diligence to industry standards means. If you leave out the exits, “you didn’t ask” isn’t an answer.

Integrations have their fire exits too. Here’s a declared requirement from Steve Trucking, the delivery company we’ll design for through this course: send the day’s delivery counts to the finance system every night. That’s the whole sentence the business gives you. Now look at what they’re expecting without saying it.

Click to enlarge

One declared sentence, five fire exits nobody asked for.

None of those five appears in the requirement. Every one of them would be on the list of complaints if it were missing.

See the Errors Before They Happen

So with integrations especially, we have to see errors before they happen. The client won’t ask for error handling. They’ll assume it. They won’t tell you what happens when the finance system is down for maintenance at midnight, or when a run is sent twice by accident. They’ll assume you thought of it.

That’s where the questions from the first module of this chapter come back: who calls whom, how much, how often, and what happens when it fails. The last one is the implied requirement on every arrow. For every arrow I want to know where I log it, what I tell the user, and how I retry, and I want to know it before the first line is built, not after the first failure in production.

A Three-Year Horizon

The other big implied requirement is time. The client describes the business as it is today. But nobody wants an integration that only works for today.

I like a three-year horizon. Records will grow. Traffic will grow. Users will grow. Complexity will grow. So we have to draw the volumes out of the business, not just for today but for the next few years, and design for those.

Let’s do the math once, with Steve Trucking’s numbers. It makes about 3,300 deliveries a day today, and every one of them ends up in those nightly counts. My usual growth baseline is 30% a year. That’s about 4,290 a day next year, about 5,580 the year after, and about 7,250 a day in year three: more than twice today’s number. An integration designed for 3,300 deliveries a day, with no room to grow, is a building with no fire exits for the people who’ll move in later.

That’s the first time you’ll see me do that arithmetic, and it won’t be the last. It has a name, Steve’s Number of Zeros, and chapter 6 teaches it properly, along with the whole method for drawing requirements out of the business.

What an Architect Decides Here

• What’s already on the ground: which systems stay, which go, and which ones the new integrations must connect.
• Which requirements are declared, and which implied ones the business is expecting without saying.
• For every arrow, what happens when it fails, decided before it’s built.
• Which volumes to design for: today’s, and the three-year horizon.
• Which implied requirements to write down and confirm with the business, so they become declared.

Beyond the exam: what AI changes. AI is good at turning a short requirement into a long list of questions: give it “send the counts to finance every night” and it will suggest failure, duplicates, volumes and security. Use it to widen the list. But it can’t know which of those your business actually expects, or how big year three will be. Only the people who run the business can confirm that, and the architect has to ask them.

Explore

• The next module, Owners, Boundaries and Change: what happens to an integration when one side changes.
• Chapter 6, Understanding Integration Requirements: the full method, including Steve’s Number of Zeros.