Lesson 1 of 6
Before You Write Code: What to Find Out About a Customer's System
Learn the five things to find out about a system you do not own, why you ask for the least access that works, and how to record it all on one page.
5 minForward Deployed Engineering
After this lesson you will be able to list what you must find out about a customer's system before you connect anything to it, explain why you ask for as little access as possible, and write a one-page integration sheet.
A forward deployed engineer (FDE) builds for one customer at a time, inside that customer's setup. Sooner or later the work needs data from a system the customer owns and you do not. This course takes one such job from the first questions to a running sync that the customer can look after.
The case
One made-up customer runs through every lesson. Fernhill Housing is a housing association: it rents out a few thousand homes and repairs them. Tenants report repairs to Fernhill's contact centre, and the repairs are recorded in Fernhill's housing management system.
You work for a software company whose product plans each day's jobs for repair teams. Fernhill has bought it for the contractor that does its repairs. The product is only useful if it holds Fernhill's repairs, so your job is to copy repairs from Fernhill's system into your product's job list and keep the copy up to date.
It sounds like a small job, and the code is small. Most of the work is finding out how Fernhill's system behaves and agreeing what you may do with it.
Five things to find out
Ask these before you write any code. Each answer comes from a person, so each one also tells you who to go back to later.
- Where does the data live, and who owns that system? You need a named owner who can answer questions and approve changes.
- How can data leave the system? There may be an API, a scheduled export file, or only a database.
- Who grants access, and what kind of account will you get?
- What are the limits? How many requests may you make, at what times, and is there a test copy of the system?
- What is in the data? Which fields do you need, which are personal, and who must agree to them being copied?
At Fernhill the answers came from three people. The IT lead owns the housing management system. It has an API that lists repairs, and there is no test copy. The repairs manager knows what the records mean: which statuses exist, what the priorities are, and which repairs go to the contractor. The data protection lead decides which personal data may leave Fernhill's system.
How data can leave, in order of preference
An API that the customer's supplier documents and supports is the first choice. It is meant for other programs, it has an access control of its own, and the supplier will usually warn of changes.
A scheduled export file is the second choice. It is simple and safe, but it is only as fresh as the last export, and its layout can change when somebody edits the report.
Reading the customer's database directly is the last choice. The tables were never meant for you, they can change with any upgrade, and a slow query from you can slow the system for everyone. Many customers will rightly refuse it.
Fernhill has an API, so this course uses one. The same habits apply to exports and databases.
Ask for the least access that works
Ask for an account that belongs to the integration and not to a person. If it is a person's account, the integration stops on the day that person leaves, and nobody can tell the person's own actions from the integration's.
Ask for read access only, and only to the records you need. You are copying repairs, so the account should not be able to change a repair or read rent accounts. A narrow account protects the customer if the token leaks, and it protects you: nobody can blame the integration for a change it is unable to make.
Agree how the token reaches you and where it will be kept. It should never travel by email or chat, and it should have an expiry date that somebody has written down.
Personal data
A repair record holds a tenant's name, phone number and address. Decide what to copy one field at a time. The rule is to copy what the job cannot be done without, and nothing else.
At Fernhill the data protection lead agreed that the address and postcode may be copied, because a repair team cannot arrive without them. The tenant's name and phone number may not, because Fernhill's contact centre arranges every appointment. Get that decision in writing. It will shape the code in lesson 4.
The integration sheet
Put the answers on one page and send it to the people who gave them. They will correct it, and a corrected sheet is the agreement you build to. Here is Fernhill's.
# Integration sheet: Fernhill Housing repairs
## System and owner
Housing management system. Owner: Fernhill's IT lead.
Meaning of the records: the repairs manager.
## How the data leaves
The system's API: a list of repairs, read page by page.
It can return only repairs changed after a given time.
## Access
One token for this integration. It can read repairs and nothing else.
Issued by the IT lead, passed on through Fernhill's password manager.
Expires after twelve months. Renewal: ask the IT lead.
## Limits
At most one request a second. Sync at most every fifteen minutes.
No test copy of the system exists.
## Data
Copied: reference, address, postcode, category, priority, reported
date, status, time of last change.
Not copied: tenant name, tenant phone (agreed with the data
protection lead).
## Open questions
- Which categories exist, and which go to the contractor?
- How are cancelled repairs shown?
- How much notice will we get before the API changes?
## Contacts
IT lead (access, faults), repairs manager (meaning of the data),
data protection lead (personal data).Set up for this course
Because Fernhill has no test copy, you will practise against a small program that behaves like Fernhill's API and runs on your own machine. You will start it in lesson 2.
You need Python 3.9 or later and nothing else. Create a folder called integration and keep every file from this course in it. Where the course writes python, use python3 if that is the command on your machine.
Key takeaways
- An integration is mostly agreed before it is written: where the data lives, how it leaves, who grants access and what the limits are.
- Prefer an API the customer already supports to an export, and an export to reading their database.
- Ask for an account that belongs to the integration, can only read, and can only read what you need.
- Decide field by field which personal data you copy, and get the customer's agreement in writing.
- Keep the answers on a one-page integration sheet that the customer can check.
Try it
Choose a system you know from work or daily life that holds records, for example a booking system, a shop's stock list or a school register. Imagine another program needs a daily copy of some of those records. Write an integration sheet for it with the same seven headings as the Fernhill sheet. Where you do not know an answer, write the question you would ask and who you would ask. A good result names a person or role under "Owner", lists at least one field you would deliberately not copy, and has at least two open questions.
Official documentation
Written with AI and checked automatically. Nobody has run these steps by hand, and tools change, so a command may behave differently in the version you install. Spotted a mistake? Tell us.