This is an old revision of the document!

YaMMS - Yet another Medical Messaging System

Message Transport Procedure

Message IDs and logging

Message ids are based on two components; The capital letter 'Y' for YaMMS and a running serial number counting from 10000.
Each message is stored in a folder with the name generated from the generation date; [year]/[month].
When a new message id is to be generated the folder with the greatest year/month is opened and the file with the greatest serial number is identified. With this number as the base a new file is created with CREATE_EXCL increasing the counter as long as the creation fails.

Receiving

Message files drop into the inbox folder from ftp in regular intervals (ex. 10 minutes).
Each message file is parsed and receipts are put in the outbox.
Each message file is added to an index containing message metadata (ex. read/unread).
Bad messages (syntax errors, unknown types etc.) are marked as such.
Control messages are used to mark uploaded messages in the outbox-waiting-confirm folder.

Sending

Inotify on the outbox triggers the sending event.
Any newly written messages in the outbox is syntax checked and validated.
Errornous messages are stalled and a message is put in the inbox that the message could not be sent.
Validated messages are uploaded to the ftp server.
Each uploaded file is put in a outbox-waiting-confirm folder and marked as uploaded but not confirmed.
Each upload also makes a download.

Http protocol (client interface)

Get inbox contents (list of messages containing id, type and resume tupples)
Move message to [trash|archive|…]
(Delete message entirely?)
Send [hospitalreferral|…]
Mark message as [read|unread|handled|…]
Get address by id.
Edit address (by id).
Create address.
Delete address.

Internal Message Format

All internal messages are in UTF-8 encoding.
All address ids maps to address entries in database on server.

Read Format

Get mailbox listing

URI: /listing?mailbox=inbox

Reply contains:

Message id
Sender address id (ean number)
Receiver address id (ean number)
Message title (message type and one line resume)
Message status
Message times (sent/received/read etc)

Reply XML:

<yamms>
  <messages mailbox="inbox">
    <message id="47720D608496E1" sender="1234567890" receiver="1234567891" status="unread"
             senttime="2011-01-01 12:01" recvtime="2011-01-01 13:01" readtime="2011-02-01 08:13">
      <title>Some title</title>
    </message>
    <message ...>
       .
       .
       .
    </message>
     .
     .
     .
  </messages>
</yamms>

Get single message by id

URI: /message?id=47720D608496E1

Reply contains:

Message id
Sender address id (ean number)
Receiver address id (ean number)
Message title (message type and one line resume)
Message status
Message times (sent/received/read etc)
Message body (server generated resume based on MedCom XML)
Original MedCom XML in base64.

Reply XML:

<yamms>
  <message id="47720D608496E1" sender="1234567890" receiver="1234567891" status="unread"
           senttime="2011-01-01 12:01" recvtime="2011-01-01 13:01" readtime="2011-02-01 08:13">
    <title>Some title</title>
    <body>Dette er et eller andet smart.</body>
    <msg>IDUgbWcgMSoxIGZvciBibG9kdHJ5a2tldCAtIFRhYmwgTm9ydmFzYyA1IG1nIDEqMSBmb3IgYmxv
ZHRyeWtrZXQtIFRhYmwgQ2VudHlsIG0uIEtDbCAxIGRnbCAgZm9yIEJUIG9nIHZhbmRkcml2ZW5k
ZSAtIFRhYmwgS2FsZW9yaWQgMSBkZ2wga2FsaXVtdGlsc2t1ZCA8QnJlYWsvPjwvQWN0dWFsTWVk
aWNpbmU+CiAgICA8L1JlbGV2YW50Q2xpbmljYWxJbmZvcm1hdGlvbj4KICA8L0hvc3BpdGFsUmVm
ZXJyYWw+CjwvRW1lc3NhZ2U+Cg==</msg>
  </message>
</yamms>

Control Messages

Control messages are only shown to the user if they contain errors (are of type CTL01 of CTL02). These messages also include a ref attribute (int the message tag) that referrer to the corresponding message id. The client can then request the erroneous message and show it to the user at will.

Send Format

Contains:

Sender address id
Receiver address id
A list of required fields

VANS communication

All VANS communication is done using existing scripts. YaMMS simply gets its own inbox/outbox. The path for these folders are stored in the server config file.

<!-- Gammelt:
Connections to the VANS ftp server are done by using libcURL.\\
A connection session consists of the following actions:
  * Connect
  * Get VANS-inbox directory listing.
  * Download VANS-inbox files to local inbox.
  * Delete VANS-inbox files.
  * Get local outbox directory listing.
  * Upload local outbox files to tmp folder on VANS-server.
  * Move files from tmp folder on VANS-server to VANS-outbox.
  * Delete local outbox files (move to archive?).
  * Disconnect.
The procedure is activated either by a timer-timeout event (eg. every 10 minutes) or when a client request the sending of a message (a message is put in the outbox).
A separate single shot timer may be introduced connecting 10 seconds after an upload has been made in order to check for immediate negative-VANS control messages.
 
Using libcURL with ftp: http://stackoverflow.com/questions/2162022/downloading-all-files-in-directory-using-libcurl
-->

Message Metadata

Messages have meta data. These meta data are to be stored in something resembling a relational database.

Meta data are mappings from message id to a tuple like this one:
message id → (read status, control message status)

Furthermore the meta data storage system can be used to store a counter used for generating unique Envelope/LetterIdentifiers.

Evaluating storage methods:

Postgres/MySQL
- Pros:
  - Easy accessible and fast.
- Cons:
  - Shooting tits with guns, ie. very small amounts of data in a very large database system.
  - Database data is 'disconnected' with the message files themselves, making backup trickier.
  - Hard to reconstruct upon corruption.
SQLite/BerkleyDB
- Pros:
  - Easy accessible and fast.
  - Database data are (can be) stored together with the message files.
- Cons:
  - Hard to reconstruct upon corruption.
XML/txt file stored in each message folder
- Pros:
  - Easy accessible.
  - Meta data are stored together with the message files.
  - Easy to reconstruct upon corruption.
- Cons:
  - Potentially slow since each files needs to be read upon directory access.
Wrap message XML in a storage file (XML) and store the message meta data with the message.
- Pros:
  - Meta data are stored together with its message.
  - Meta data are easy to .
  - Easy to reconstruct upon corruption.
- Cons:
  - All message files needs to be read in order to do searches.
  - Message files needs to be rewritten whenever meta data changes.

Aasimon.org Wiki

Table of Contents