🔗 Source article (Salesforce): Click here
About the Timestamping Module
Introduction to the web services interface
Required configuration before starting to use the web services
General technical information
General request and response information
Request information
Response information
JournalEntryService - AddJournalEntry
Description
Request message
Response message
JournalEntryService - AddAttachmentJournalEntry DEPRECATED
Description
Request message
Response message
GenericDocumentService
Description
Request message
Response message
Status codes from the Timestamping Module
Generic Document
Meta data Type
Document Type
Example
JournalEntryService - AddJournalEntry
Request message
Response message
JournalEntryService - AddAttachedJournalEntry DEPRECATED
Request message
Response message
GenericDocumentService - AddGenericDocument
Request message using base 64
Request message using Reference DEPRECATED
Response message (Success Response)
Error messages
Invalid Application Token Response message
Invalid request (validation exception) Response message
Introduction
About the Timestamping Module
"Within the Belgian hospitals more and more ICT systems are being introduced to support the daily operations. As a consequence the hospitals are migrating towards a paperless environment, where the information is stored only electronically. This makes it more difficult for the supervising authorities to fulfil their duties, as today the paper documents are the most important source of proof of activities.
But migrating to an environment where all information is kept in an ICT environment also introduces new opportunities. One of these opportunities is the possibility to provide an irrefutable proof a certain piece of information existed on a given date by means of a trusted third party time stamp.
That means that at the moment one wants to verify a time stamp, the hospital information system is likely to have evolved, so that reconstructing the journal entry might not be straightforward, especially as –to prove the correctness of the timestamp- the reconstructed journal entry should be identical to the original one up to the bit level. We consider this as too error prone and costly to implement. It would require that with each version change of a clinical system some sort of bit-level compatibility should be assured, checked and maintained over the years. Changing to a totally different clinical system would require complete embalmment of the old system in a resurrectable state in order to be able to regenerate the original statements.
Therefore we will archive not only the time stamps, but also the journal entries that have been time stamped. The set of these journal entries will constitute the journal (logboek, journal de bord) of the hospital. The information to be time stamped will be extracted from the hospital information system and archived independently of the hospital information system. These journal entries will be self contained, so that they can be interpreted without consulting external information sources.
All documents will contain the identification of the doctor involved, the patient involved, the type of journal entry and the time the document was generated."
(extract from the eHealth-platform Timestamping Technical Documentation)
The Timestamping Module is an out-of-the-box software that allows to sign with a timestamp any type of electronic document, using the Timestamping service provided by the eHealth platform.
For each document inserted in the entry queue via a web service described in this document, an ID is generated, and a hashing file is produced and signed via the Timestamping service of the eHealth platform. The document and signed hash are finally saved in an archive database in the hospital.
The SW product also allows to retrieve a document in the archive of the hospital and to verify the validity of its hash and timestamp.
This Module can typically be used in the context of hospital electronic medical prescriptions.
The Timestamping Module includes its own process responsible for the timestamp calculation and registration. This process is inspired by the reference application of the eHealth platform, available in freeware, open source (license Apache 2.0). HealthConnect added the following functionalities:
A Web service interface (JournalEntryService) to insert a message or document in KMEHR format in the entry queue.
An extended Web service interface (GenericDocumentService) enabling to transmit any other type of document (PDF, TIFF, JPEG, HL7, other XML) with extra metadata on the document to be signed and archived
An administration console including a dashboard to follow and manage the Timestamping Module activity (for ex. counters of number of documents processed per day, etc.)
An archive documents visualisation Web application easily accessible via the hospital intranet.
Introduction to the web services interface
The Timestamping Module web services interface allows submitting document to the entry queue (Input Buffer) of the Module. These documents are then asynchronously timestamped using the HC timestamping process and stored in the TS Archive.
In the current version, the following web services are available:
The JournalEntryService web service: To be used to submit XML documents in KMEHR format (like medical prescriptions). The following operations are available:
AddJournalEntry -> to insert a KMEHR doc (encoded in base64) via the soap body
AddAttachedJournalEntry -> same but via a soap attachment
The GenericDocumentService web service:To be used to submit any other type of document. The following operation is available:
AddGenericDocument -> to insert any other type of doc (encoded in base64, or via reference) via the soap body
This document contains the required information to create a client application integrating these web service operations.
Required configuration before starting to use the web services
Before an external client application can invoke a web service operation successfully, the following configuration must occur by the Timestamping Module administrator within your organization:
Create an application within the Timestamping Module management function
Using the Timestamping Module administration console (a web application), an administrator is able to define a new application that can connect to the Timestamping Module WS interface. A token is attributed automatically by the Timestamping Module administration application when registering a new application. This application token uniquely identifies a client application and it must be added to each request.
General technical information
Before integrating the TS Module interface, please take into account the following principles and considerations.
The TS Module web services provide synchronous communication. After invoking a request, a response is returned immediately.
A response message returned by the TS Module can be a normal SOAP message or a SOAP Fault.
A generic SOAP Fault is returned when the request message contains invalid input parameters (WSDL file or SOAP definitions not respected, or server problem).
A normal response message is returned when the TS Module has successfully inserted the document in the Input Buffer queue, or when a specific Timestamping error or a business error has occurred (for ex. when the TS Module detected a security violation or when a general technical exception occurred).
More information about possible error messages is available in chapter 3.
For each web service operation, the request and response messages are detailed.
Description of the web service operations
General request and response information
Request information
All web service operations contain a generic block of request parameters (RequestInfoType).
[ IMAGE: rtaImage ]
General request parameters are required for each web service operation. They are used to uniquely identify the calling application/end-user and to gather some general information to process the request and response.
Name
|
Description
|
Application Token
|
Security token to uniquely identify the application invoking the request. This is a general token that is attributed automatically by the Timestamping Module administration application when registering a new application. Please contact your Timestamping application administrator to receive the token.
|
User Id
|
Unique identifier of the end-user initiating the request.
|
Language
|
Currently this parameter is not used but added for compatibility reasons
|
Client Message Id
|
ID to uniquely identify the request message. If provided, the value will be returned in the response message.
|
Response information
The different web service operations return a generic set of response parameters. They can be used to verify if the operation was executed successfully.
[ IMAGE: rtaImage ]
Name
|
Description
|
Code
|
Status code of the request message. This code indicates if the message was executed successfully or if an exception occurred.
|
Message
|
Description of the status code.
|
Message Id
|
Unique identifier of the request/response message. Assigned by the timestamping module.
|
Client Message Id
|
Identifier provided by the client application invoking the request. Only available if a Client Message Id was available in the request.
|
JournalEntryService - AddJournalEntry
Description
The AddJournalEntry operation allows submitting a document to be timestamped to the entry queue of the TS module. Document is transmitted in the SOAP body.
Request message
Besides the generic request parameters (RequestInfoType, described in section 2.1.1) required for each web service operation exposed by the TS Module, two input parameters are required:
the Document itself in base64 encoding.
the type of the document
[ IMAGE: rtaImage ]
Name
|
Description
|
Data
|
The document byte stream in base64 encoding
|
JournalType
|
Value must be "kmehr"
|
Response message
Nothing in addition to the General response in section 2.1.2
JournalEntryService - AddAttachmentJournalEntry DEPRECATED
Description
The AddAttachmentJournalEntry operation allows submitting a document to be timestamped to the entry queue of the TS module. Document is transmitted as a SOAP attachment.
Request message
Besides the generic request parameters (RequestInfoType, described in section 2.1.1) required for each web service operation exposed by the TS Module, two input parameters are required:
the Document itself in base64 encoding.
the type of the document
[ IMAGE: rtaImage ]
Name
|
Description
|
AttachmentId
|
The document byte stream in base64 encoding
|
JournalType
|
Value must be "kmehr"
|
Response message
Nothing in addition to the General response in section 2.1.2
GenericDocumentService
Description
The AddGenericDocumentRequest operation allows submitting a document to be timestamped to the entry queue of the TS module. Document is transmitted in the soap body as base64 or as a reference.
When a document is timestamped as a reference, make sure the timestamping module can access and download the referenced location.
Documents provided via a reference will not be persisted by the timestamping module. In that case the hosting system of the reference should keep on persisting it (and provide the necessary backups). The metadata will be persisted by the module. This feature is typically used for large (>1 MB) files.
Documents provided as base 64 or via reference (http, ftp) will be stored together with its metadata in the module. For documents bigger then 5MB use the reference strategy.
Request message
[ IMAGE: rtaImage ]
The generic request parameters (RequestInfo) are described in section 2.1.1.
Name
|
Description
|
GenericTtsDocument
|
Structure described in section 4.1.
|
Response message
Nothing in addition to the General response in section 2.1.2
Error messages
As described earlier in this cookbook, each response message contains a generic ResponseInfo structure that provides status information (a code and message). In most scenarios when a SOAP Fault occurs, an identical ResponseInfo structure is available.
If a correct response message is returned by the eHealth platform, the status code of the eHealth platform is returned. If an exception occurred within the timestamping module, a specific timestamping status code is returned.
The tables below provide an overview of some of the error codes.
Status codes from the Timestamping Module
If an exception or error occurred while processing the web service request by the Timestamping application, a SOAP Fault will be returned as response. This SOAP Fault will contain a ResponseInfo object with a detailed status code and message. Examples are available in section 0.
Code
|
Message / Description
|
100
|
"Service successful"
|
9001
|
"Failed to validate against schema" (+ detail info on the error when available)
|
9002
|
"Invalid binary content provided".
|
9003
|
"Invalid attachment identifier/No attachment"
|
9004
|
"Journal type not specified"
|
9005
|
"No journal data"
|
9006
|
"Invalid reference to document"
|
9007
|
"Reference not found"
|
9100
|
"Invalid request"
|
9101
|
"Invalid userid"
|
9102
|
"Invalid application Token"
|
9199
|
"Invalid parameters provided"
|
9201
|
"Security exception while invoking timestamping service"
|
9299
|
"A general exception occurred".
|
Generic XML structures
Generic Document
A XML schema has been created that details a "Generic Document" to be time stamped (generic-document-1-0.xsd).
The following figure provides an overview of the XML document that is capable of representing any type of document to be time stamped. It consists of 2 distinct elements:
Meta data
The document itself (encoded as a binary64 stream) or as a reference
[ IMAGE: rtaImage ]
Meta data Type
"MetaData" contains the required Type element and multiple String, Date and/or FullText elements. These elements must be used to register meta-data to the TTS archive database and are useful to search for a specific document time stamped in the past.
Name
|
Description
|
Type
|
Type of the document to be time stamped. The possible values are not restricted, although it is highly recommended to use a pre-defined list.
|
String
|
[ IMAGE: rtaImage ]
|
Date
|
[ IMAGE: rtaImage ]
|
FullText
|
[ IMAGE: rtaImage ]
|
Document Type
[ IMAGE: rtaImage ]
Name
|
Description
|
Title
|
Title of the document that is time stamped.
|
MimeType
|
Mime type associated with the Binary Content. Please refer to the official list (example: http://www.iana.org/assignments/media-types/) Examples: application/xml, application/pdf, image/tiff
|
BinaryContent
|
Base64 encoded document.
|
UriReference
|
A reference to the orginal document that needs to be timestamped. The service offers support for http(s), ftp and network paths.
|
Example
See examplePDF.xml file for an example with a PDF document.
See exampleTIFF.xml file for an example with a TIFF document.
Example messages
JournalEntryService - AddJournalEntry
Request message
|
Response message
|
JournalEntryService - AddAttachedJournalEntry
Request message
|
Response message
|
GenericDocumentService - AddGenericDocument
Request message using base 64
|
Request message using Reference
|
Response message (Success Response)
|
Error messages
Invalid Application Token Response message
|
Invalid request (validation exception) Response message
|