The system nobody may touch
The university's student-records system went live twenty years ago, and the contract with its vendor forbids any change to its code or its database. Nobody at the university may add a hook, a trigger or a line that publishes an event. The system will go on doing exactly what it does today.
Meanwhile three new services need to know when a student enrols or withdraws. The library issues and cancels access cards. The accommodation office holds and releases rooms. The student app shows a timetable to enrolled students only. All three would like that news as messages on the university's broker, and the records system has never sent a message in its life. What it does offer is this:
- a nightly export, a CSV file with every student and their current status, written to a shared folder;
- read access to a reporting copy of its database, which the vendor supports for the university's own reports;
- the report screen the registry staff use, which lists the day's status changes.
None of these is messaging. Each is a way to read the system from outside, and that is enough.
Something outside that speaks for it
A Channel Adapter is a component outside an application that uses an interface the application already has on one side and a message channel on the other, so the application joins the messaging world without being changed. Named from the messaging side, an inbound adapter goes from the application to the channel: the records adapter reads student records and publishes StudentEnrolled and StudentWithdrew on a student-status channel. An outbound adapter goes the other way, from the channel to an application.
The university needs one of those too, because the library runs a packaged product that knows nothing about messaging either. An outbound adapter subscribes to student-status and calls the product's API to create or suspend a patron account for each message. Neither application changes; each adapter is the only piece that knows both worlds.
The inbound adapter reads the records system and publishes events. The outbound adapter turns the same events into calls to the library product's API. Accommodation already consumes messages and needs no adapter.
The records adapter also decides what the messages look like. The reporting tables record a withdrawal as STU_STAT_CD set to W against a term code such as 2026A; the message says StudentWithdrew, with the student's id and the date it takes effect. That mapping is a Message Translator, inside the adapter or as the step after it. Either way the library, accommodation and the app never learn the vendor's column names, and a vendor upgrade changes one adapter instead of three services.
Its neighbours do other jobs. Code the university can change, such as the new student app, calls a Messaging Gateway instead; the code inside an application that connects it to one channel is its Message Endpoint; and two messaging systems are joined by a Messaging Bridge. A channel adapter is for what is left: a system that cannot be changed, or that knows nothing about messaging at all.
Three ways in, three blind spots
How the inbound adapter gets data out matters more than anything else about it, because it decides what the adapter can see.
The nightly export is the obvious start. The adapter reads each night's file, compares it with the previous one and publishes a message for each student whose status changed. It uses something the vendor documents, and it sees one picture of the university a day. A student who withdraws keeps a working library card until the next export, and a student who enrols and withdraws between two exports never shows as enrolled in any file, so no service ever hears of the enrolment. The failure that hurts arrives the night the export stops halfway and writes 3,100 of its 18,000 rows. An adapter that reads a student missing from the file as a student who left publishes 14,900 withdrawals, and the library suspends 14,900 cards. So the adapter checks the file before it trusts it: an end marker, if the export writes one, and a row count compared with the previous file, refusing a file that shrank by more than a few percent and alerting someone instead.
Polling the reporting database cuts the delay to minutes. Every five minutes the adapter asks for enrolment rows changed since the last one it saw, using a last-updated column the table carries. It still sees states, not changes: a status that flips and flips back between two polls is invisible, a row the vendor deletes outright never comes back from a query for changed rows, a change written without updating that column is missed, and so is one committed after a poll has already moved past its timestamp. A reporting copy can also run behind the live system. The university keeps the nightly export as a reconciliation, sending a correction for each student whose status in the file differs from what polling had published by the time the file was written; a change both of them missed stays missed.
Reading the database's own change log, where the vendor permits it, sees every committed change to the tables it captures, deletes included, in the order the log records them, as long as the adapter keeps up with what the log retains. A connector that does this is a channel adapter for databases, and Change data capture explains how it works. It needs database permissions a vendor may refuse. The report screen is the last resort: an adapter that scrapes it can break whenever the layout changes, and sees only what the screen shows.
Where the adapter left off
Polling means remembering a position, the last row the adapter published. The adapter publishes first, waits for the broker to confirm, and only then records the position, and a crash between the two means that on restart it reads from the old position and publishes the same withdrawals again. Recording first would trade that for a crash that loses the withdrawals, and a student who left would keep library access nobody revokes. So a re-published row can reach consumers more than once. The adapter's part is to give each change an id that no other change shares and that stays the same every time it is published: the record's key with a row version the source keeps, or an id the adapter records with the change before it publishes. The consumers' part is Idempotent Consumer.
Student records in the Challenge
The Messaging Endpoints & Broker challenge places the adapter in a wider picture that also needs a gateway, endpoints, a broker and a wire tap. For the adapter's part, put the student-records system in as the external system with the records adapter beside it, label the edge between them with the way in you chose and its delay, and give the records system no other edge, so the diagram shows the adapter as its only way into messaging.
What the adapter answers for
The records system will never know the adapter exists, so everything the new services believe about enrolments is only as good as the adapter's way in. A withdrawal it cannot see does not exist for the library, a file it trusts without checking becomes thousands of real suspensions, and a position it records too early loses changes for good. Choosing the way in is choosing which of those risks the university lives with, and making that choice visible on the adapter's edge is most of the design.