Resources · Framework
Integration Specification Template
Eight sections. Written properly, they are what make three quotes comparable — and comparable quotes favour the vendor who is not pricing a contingency against everything the brief failed to say. Copy it, print it, and use it on us as readily as on anybody else.
Before you start
UNIT 01Most integration briefs describe a solution. That is understandable and it is expensive: a brief that opens with a technology gets quotes for that technology and rules out the cheaper answer nobody was asked about. It also makes the quotes incomparable, because each vendor fills the gaps differently and prices its own guesses.
The sections below are ordered the way an experienced integrator reads a brief. Sections 02 and 03 — the asset list and the tag list — are worth more than the other six put together. A brief with those two done properly will get you a real price. A brief without them will get you a range, and the range will be wide in the direction that protects the vendor.
You will not have every answer. Write “not known” where that is true rather than leaving a blank — a stated unknown is something a vendor can price a survey against, and a blank is something they will price a contingency against.
The outcome, in one paragraph
01Vendors solve the problem they were given. A brief that opens with a technology rather than an outcome gets quotes for that technology, and rules out the cheaper answer nobody was asked about.
What to write
- What can you not do today that you need to do?
- Who is affected, and what changes for them on the day it works?
- What would you measure in six months to know it worked?
- What is the cost of continuing exactly as you are?
The mistake
Naming the solution in the first line. "We need a dashboard" is an answer; "we cannot tell which line lost the hour" is a brief, and it might not need a dashboard.
Assets in scope
02The single largest cause of variation. Scope written as a category — "the pumps" — is priced as an average and delivered as a discovery.
What to write
- List every asset by make, model and year. Not by category.
- For each: what interface does it have, and who holds the credentials?
- Which is the least accessible? The project is paced by that one.
- Which assets are explicitly out of scope, and might be added later?
The mistake
Leaving out the one machine everybody knows is a problem, on the basis that it can be dealt with later. It will be quoted for later, at a worse price, by somebody with less leverage.
The tag list
03The most useful document you can produce before going to market. Vendors quoting without one are quoting a guess, and the variation later will not be a guess.
What to write
- Every value to be read or written: name, source asset, address if known.
- Data type, engineering units, and expected range for each.
- Required sample rate for each — and be honest, because rate drives cost.
- Which values are read-only and which, if any, are written back.
- Retention: how long each value has to be kept, and why.
The mistake
Asking for everything at one second. Sample rate is the cheapest thing to over-specify and one of the more expensive things to deliver, and a controller sized in 2008 will not enjoy it.
Where it has to reach
04The number of boundaries crossed drives cost far more than the cleverness of what is built.
What to write
- Which systems does the data have to land in? Name the product and version.
- Does anything flow back down towards the plant? If so, what, and who authorises it?
- Who owns each of those systems, and have they agreed to this?
- What happens to the flow when one end is unavailable?
The mistake
Assuming the owner of the receiving system has agreed. On more than half of stalled projects, they had not been asked.
Network and access
05Integration is what makes an informal network boundary load-bearing. Specifying it after the build is a change request; not specifying it at all is an incident.
What to write
- How are plant and business networks separated today?
- How will the vendor obtain access during the build, and how is it revoked?
- Who owns security for the operational side, by name?
- What must never be reachable from outside the plant?
The mistake
Leaving vendor access to be arranged informally on day one. It becomes a standing account that is still open in three years.
Constraints that are not negotiable
06Constraints discovered mid-build are variations. Constraints stated up front are design inputs, and cost nothing.
What to write
- What downtime is available, when, and how far in advance must it be booked?
- What certifications, warranties or class requirements restrict what may be connected?
- What environmental conditions does equipment have to survive?
- Which permits are required, and how long do they take to obtain?
- Are there periods when no work may take place at all?
Acceptance
07Without written acceptance criteria, "done" is decided by whoever is more tired. With them, it is decided by a test.
What to write
- What test, run by whom, determines that this works?
- What accuracy or availability is required, measured how, over what period?
- What is the agreed behaviour when a source is unavailable?
- How long does the system run under observation before acceptance?
The mistake
Acceptance on the day of commissioning. Ask for a defined observation period afterwards — the failures worth catching are the ones that need a fortnight to appear.
Handover and exit
08The terms of leaving are decided when you arrive, and the moment you need them is the moment you have least leverage.
What to write
- What documentation is delivered, and in what form?
- Who holds credentials, licences and source at the end?
- What training is provided, to whom, and is it recorded?
- If you engaged a different integrator next year, what would they need, and would they get it?
- What does support cost after the first year, and what does it cover?
The mistake
Accepting "we'll provide documentation" without naming the documents. Ask for the list, and put it in the contract as a deliverable with its own sign-off.
The skeleton
UNIT 10Take it with you
↓The result as plain text. Paste it into an email, a board paper, or a request for quotation — no address needed, and it stays readable when it is forwarded to somebody who was not in the room.
Technical references
UNIT 11What the reasoning on this page is drawn from. Where a standard costs money to read it is marked, and where a free document covers the same ground better it is listed first.
- ISA-95Paid standardISAThe enterprise-control integration standard the Purdue level model comes from. Levels 0 to 4 as they are actually defined.
- OPC UAOPC FoundationThe specification and the security model. If a vendor offers OPC UA, this is where you check what they are actually offering.
- Modbus specificationsModbus OrganizationThe protocol specifications, published free. Worth reading the application protocol document once if anybody is quoting you for Modbus work.
Links open in a new tab so anything you have entered above survives. Every one was checked at build time; if one has rotted since, tell us and it comes out rather than getting patched from memory.
Every one of these tools is a compressed version of a conversation. If yours turned up something you would rather talk through than read about, that is what the scoping call is for — bring your result with you.
Have a draft specification reviewed before it goes outAlso on the shelf
- Framework
The Readiness Model
The five dimensions behind the readiness assessment, written out in full: what each one measures, how it fails, and what it costs to fix before a build rather than during one.
- Framework
Pilot to production
The gates a working pilot has to clear before it is allowed to run the business, and the specific ones most SME automation dies at.
- Framework
Vendor scorecard
How to compare integration vendors on what will actually determine the outcome, weighted and scored — including the questions we would rather you asked us.