In development. API spec subject to change.
PKB implements the $process-message operation as defined by the FHIR specification, in order to allow a client to submit a message for processing.
PKB will outline a MessageDefinition for each event that we support. Some behaviour will be common to all messages as part of the general $process-message specification. Each message will have its own business logic rules defined in the corresponding message definition.
The first message PKB will support is the ability to create or update a patient's demographics, including triggering an email invitation.
PKB only supports the asynchronous pattern, see below for more information.
Asynchronous design implications
Synchronous Messaging is not supported by PKB. All Messaging clients must therefore support the asynchronous pattern. This has a few implications:
Clients must expose an inbound $process-message endpoint themselves, to which PKB will send the asynchronous responses which will indicate the outcome of the processing.
Your inbound endpoint must be protected using the OAuth 2.0 client credentials workflow, which will require you to issue PKB with a client ID and a client secret. This is the same mechanism PKB uses to protect our own endpoint.
The location of your inbound endpoint must be agreed with PKB before your interface is enabled, and this value will be checked against the one provided in MessageHeader.source
Clients must provide the “async=true” parameter when calling $process-message
An inbound message will have only lightweight validation applied before the transport-level (synchronous) response is returned - just enough to accept the message into the system.
If it passes, then HTTP 202 Accepted (no body) will be returned. Otherwise, an appropriate HTTP error code will be returned, along with a FHIR OperationOutcome where possible.
All other validation is applied afterwards, and any errors will be returned from the application-level (asynchronous) response.
PKB will return exactly one response for each inbound message.
See the FHIR API Messages page for details of supported messages.