Integration overview
Diarybook runs in one of two modes. Standalone, it is the whole system — appointments are created and managed in Diarybook itself. As an integration layer, it sits alongside an existing patient management system (PMS) or hospital information system (HIS), adding automated multi-channel reminders without replacing the system clinical teams already use.
This page is the technical reference for the second mode: what connects to what, what the daily file contains, and how Diarybook matches what arrives in it.
What integrates with what
| Component | Owned by | Role |
|---|---|---|
| Source system (PMS/HIS) | You | Master record. Appointments continue to be booked here. |
| Export process | You | A scheduled query that writes upcoming appointments to a flat file. |
| SFTP endpoint | Diarybook | xfer.diarybook.com — where the daily file is delivered. |
| Diarybook Synchronisation Service (DBSS) | Diarybook | Reads the file, syncs clients and appointments into your account. |
| Reminder engine | Diarybook | Sends SMS, email, voice or letter on the schedule each reminder setting defines. |
| Diarybook portal | Diarybook | Where replies, confirmation status and attendance are visible to staff. |
Diarybook does not connect into your systems. There is no inbound access, no VPN into your network and no credentials held on Diarybook’s side against your database. Data flows outbound from your network only, which keeps the integration inside your own change control.
The on-premises side is yours. How the file is produced and uploaded — which platform, which scheduler, which SFTP client — is entirely your decision. Diarybook does not prescribe it and does not need to know how it works. Diarybook’s scope begins when a file arrives at the SFTP endpoint. What Diarybook specifies is only what this page covers: the file’s format and content, and where to put it.
Diarybook customises DBSS free of charge to accommodate the shape of your appointment data, so the export can follow your system rather than the other way around.
Clinic codes
A clinic code is a label carried on every appointment record in the file. It is the routing key for the whole integration and it is agreed between you and Diarybook — an account can have one code or many. Diarybook holds the settings against the code; you choose which settings an appointment gets by choosing which code you send it under.
The clinic code, plus optional sub-codes, determines:
| What the code sets | Effect |
|---|---|
| Diarybook user | Who the appointment is assigned to, and therefore who can see it — that user, plus other users according to their permission levels. |
| Appointment type | Filtering by type, and the colours the appointment takes in the calendar. |
| Reminder setting | The entire automatic reminder process — when the client is reminded, by which channel, and how often. A reminder setting can also link to a location record for geographical detail. |
| Sync report recipients | Email addresses (if any) the daily sync report is sent to. |
| Group tag (optional) | Used by accounts that take appointment data from more than one source. |
| Custom merge fields (optional) | Values available to the reminder message text. |
Reminder reports are separate from sync reports: the daily sync report addresses are set against the clinic code, and the daily reminder report addresses are set on the reminder setting.
Because the code is per appointment, a single account can run entirely different reminder behaviour for different clinics, departments, locations or procedure types.
Code matching
- A clinic code in the file that does not exist in Diarybook is ignored for that day.
- A clinic code in Diarybook that does not appear in the file is ignored for that day.
- If no file is found at all, every clinic is ignored for that day.
Nothing partially processes and nothing carries over: each day stands on its own.
Timing
Each clinic is processed once a day. The processing time comes from the Schedule Earliest Time field on the clinic’s reminder setting — and processing may start up to an hour earlier than that, to accommodate the one-reminder-per-client rule that stops a client receiving several reminders for the same day.
Upload well ahead of the processing time. Somewhere between 1am and 5am is the recommendation. A file that lands after its clinic has been processed does nothing for that day.
What to include in the export
With the date the file is produced as current-date, select appointments:
- whose date is on or after
current-date - and whose date is on or before
current-dateplus the days-in-advance value of the reminder setting — where several reminder settings apply, use the largest value; a wider date range does no harm - whose client has a mobile number
- that are suitable for reminders — not cancelled, for example
Deliberately include appointments that are not yet due a reminder. Diarybook ignores them until the schedule says otherwise, and it means reminder timings can be changed on Diarybook’s side without anyone having to change the export.
Multiple files are supported where the data comes from more than one source.
File format
Filename
Start the name with an account identifier, followed by the date and time of creation:
myorg_202307010600.txt
Where the integration uploads several files from different sources, put a source indicator between the account identifier and the timestamp:
myorg_mydept_202307010600.txt
Layout
Windows ASCII text. One line per appointment, fields separated by commas, each field a single data point.
| Position | Purpose | Merge fields |
|---|---|---|
| 1 | Date and time of appointment | date, dayname, monthname, day, time |
| 2 | Client’s surname | last |
| 3 | Client’s forename | first |
| 4 | Unique client identifier | id |
| 5 | Clinic code | |
| 6 | Client’s mobile number | mobile |
| 7 | Location filter (optional) | syncfield1 |
| 8 | Procedure filter (optional) | syncfield2 |
| 9 | Clinician filter (optional) | syncfield3 |
| 10 | Client filter (optional) | syncfield4 |
| 11–16 | Spare — available for custom values | syncfield5–syncfield10 |
| 17 | Address line 1 | add1 |
| 18 | Address line 2 | add2 |
| 19 | Address line 3 | add3 |
| 20 | Address line 4 | add4 |
| 21 | Address line 5 | add5 |
| 22 | Email address | |
| 23 | Landline |
Fields 1 to 6 are mandatory; 7 to 23 are optional. The merge fields column gives the name each value takes in reminder message text — see the merge field reference for the full set.
- Field 1 holds both date and time, as either
yyyy-MM-dd HH:mmoryyyy-MM-dd HH:mm:ss. Tell your Diarybook account manager which one you are sending during setup. - Field 5 is what Diarybook uses to find the message schedule.
- Field 6 is mandatory, and lenient about format —
087…,35386…,0035385…,+35387…and87…are all accepted.
Example
2023-07-12 08:00:00,Bloggs,Joe,X472949,Dermatology,0871234567,Our Hospital,Phone Follow Up
Rows that fail
Nothing is silently dropped. The daily sync report lists the clients that were synced and the clients that were not. In addition, an errors report is sent if the row or file is malformed in any way causing unpredictable results. Set the sync and error report recipients against the clinic code — see Clinic codes above.
Transferring the file
| SFTP server | xfer.diarybook.com |
| Port | 22 |
| IP address | Available on request — use the DNS name unless your setup cannot. |
| Source IP address | Yours must be given to Diarybook in advance for allowlisting. |
Your Diarybook account manager issues the credentials. Diarybook can also supply the server host key details if you need to verify the endpoint when connecting.
Any SFTP client will do. Using PSFTP, the command-line utility that ships with PuTTY:
psftp -batch -P 22 -hostkey <fingerprint supplied by Diarybook> username@xfer.diarybook.com -pw XXXX filename_here
How records are matched
Clients are looked up on the unique client identifier in field 4. A match updates the existing client record; no match creates a new one. Sending a stable identifier matters for more than tidiness — it is what stops a client receiving several reminders for appointments of the same type on the same day, and it stops duplicate client records accruing on the account.
Appointments are added on first sight. An appointment already present is kept alive by the file: the keep-alive is how Diarybook knows the appointment has not been cancelled or moved at the source end, and that it should stay in scope for reminders.
The file is therefore the current truth, and two consequences follow from it:
| What happens at source | What Diarybook does |
|---|---|
| The appointment stops appearing in the file | It is marked expired. It stays visible on the account, but is ignored from then on — no further reminders. |
| The appointment’s date or time changes | The changed appointment arrives as a new appointment, and the previous one expires. |
Nothing has to be sent to cancel or amend an appointment: leaving it out of the file, or sending it with a new date, is the instruction.
Security and data protection
Appointment data reaches Diarybook over SFTP, outbound from your network, with your source IP allowlisted at Diarybook’s end. The assessor-facing material, including certifications, is in the trust centre.
The SFTP service is write only. No files can be downloaded from it. Files uploaded are processed on the same day. Files are kept for 7 days and then moved to an archive folder. Files in the archive folder are deleted after 1 year (or sooner by written request or with account closure).
Limitations
State these plainly to anyone assessing the integration.
- One processing run per clinic per day. An appointment booked after the file is produced waits for the next day’s run, which matters for short-notice appointments.
- A missed upload means a missed day. No file, no processing — for every clinic, not just the affected one. Nothing is retried or caught up.
- Codes must match on both sides. A clinic code that exists on only one side is ignored for that day rather than raising an error — and because sync report recipients are set against the code, an unrecognised code produces no report to notice it by.
- Inbound is batch; outbound is not automatic. Changes made in the source system reach Diarybook on the next daily run. Nothing travels the other way unless you take the optional write-back route, where Diarybook posts each client reply to an endpoint you host — see Requirements and compatibility. Otherwise replies live in the Diarybook portal.
- SMS replies carry no appointment context. If a client has two appointments on the same day and replies once, Diarybook logs the reply against each, marks them Tentative and notes that the client’s intention is unclear. Staff resolve it manually.