Inbox & Outbox pattern

When the case engine executes a task, such as creating a case, a lot of actions are performed. Records are saved in databases, messages are published to queues. Any of these actions can go wrong, for instance because the database is offline or there is a network error when publishing a message. When something goes wrong, the case engine repeats the task so it can be processed again. This works for changes to databases which are run inside a transaction, which either succeeds or fails completely (either everything is committed to the database successfully or nothing at all). With messages published to a queue, this is a different story. When a message is published to a queue and then something goes wrong, the message will stay on the queue. Then when the action will be repeated, because something went wrong, this will lead to the same message being published to the queue again. When you consider trace events, this would mean that the same event (e.g. case is created) would be sent multiple times and therefore end up in the trace database multiple times. This is obviously not what we want.

Outbox pattern

To prevent the same message to be published multiple times, we use the outbox pattern. The outbox pattern saves a message to an outbox table instead of publishing it directly. This happens in the same transaction as database actions are performed. This means that either everything succeeds (and the message is committed to the outbox table) or everything fails and nothing is committed to the outbox table. When everything succeeds, the message resides in the outbox table and still needs to be sent. This happens in a different process which reads the outbox table and publishes messages found there.

By using the outbox, when a task fails in the case engine, it can be completely repeated as no messages will be published to a queue or saved to an outbox table. Only if everything succeeds, a message will be saved in the outbox table and it can be sent.

There is one catch with this pattern: the process that reads from the outbox table and then publishes the message, suffers from the same problem for which we introduced the outbox pattern in the first place. That is, the message that is read from the outbox table is published to a queue and then removed from the outbox table. If something goes wrong with changing the outbox table (e.g. removing the message, committing the transaction) after the message is published, it will be published again the next time the publishing process starts.

Note that it is still valid to have the outbox pattern despite of this, because the outbox pattern guarantees that messages that are published to the queue are valid given the state of the case engine, while without this pattern we cannot guarantee this. This means that without the outbox pattern messages may be published to a queue which conflict with the state of the case engine, for instance a message is published to the timeline queue that a task is started, but starting has failed and while repeating the task in the case engine, process evaluation leads to a different task so the task is never actually started (despite what the timeline will now display).

Inbox pattern

So we still have to deal with the same message published multiple times. We can do this by applying the inbox pattern. The inbox pattern also uses an inbox table in which incoming messages are stored. This happens in the same (database) transaction as which the other database related actions are performed. This means that when an action completes successfully, everything is saved in the database including the message in the inbox table. When something goes wrong, nothing is saved in the database. Now when a message arrives, the inbox table is checked if the message already has been processed. This is the case when the message is already contained in the inbox table. When it is, we know that the message already has been processed so it can be skipped. When it is not contained in the inbox table, we have not handled this message before (or we did try but something went wrong), so we can go ahead and handle the message.

So although the outbox pattern may publish the same message multiple times, by using the inbox pattern we can still guarantee that the same message will only be handled once.

Data storage

The outbox table only contains entries before they are published. The publishing process runs regularly and empties the outbox table, which means that the outbox table will usually only contain a few records or none at all. This is different for the inbox table. As every message* that is handled will be stored here, it can grow fast. Note that instead of the entire message, only the message identifier and creation date is stored in the table, but over time this can still grow large.

There is a point in time in which messages can be removed from the inbox table as they are no longer relevant to check for, but this point in time cannot be decided beforehand, as it completely relies on the business process that is implemented with the DCM system. Therefore the monitoring and emptying of the inbox tables is a project task.