REST methods

Capricorn

Medical-Objects Capricorn is a HL7 real-time communication system for the delivery or real-time results. It has the ability to send and retrieve in a variety of formats. The Development pages lists some of the ways in which you can integrate your systems with Capricorn.

It should be noted that integration is done in Capricorn either using a tradional HL7 Fle Drop or through HL7 Lower level protocol. You can use these facilties to send communications, receive acknowledgements etc. In addition Capricorn also support integration on the local network to perform various tasks such as Send a message to a clinician, check the status of a report or letter. You can also interigate the provider directory to search for particular providers.

This local integration is done in one of two ways. All the requests are local HTTP requests and these HTTP requests can in most cases return either XML or JSON data.

Many are familiar with XML as a data format and this can be used quite easily to work with data, especially if you have an application that is writing in Java, .NET, C++, Perl etc. There are many processors of XML available to read the client. For more information on XML visit http://www.w3.org/XML/

The JSON format is mainly used on the web, so if the application you are using is a Rich Web 2.0 based system, you can still use calls to examine the local information. For more informatipon on JSON, visit: http://www.json.org/

Overview of Available Calls

The following table lists the available local calls that can be made to Medical-Objects Capricorn. Please note that this information is available primarily for organisations with clinical packages. For consulting services for integration, contact Medical-Objects at info@medical-objects.com.au.

Method	URL	Formats Supported	Formats Required Sending
IsProviderOnline	/rest/localintegration/isprovideronline?PROVIDERNO=[ProviderNo]&FORMAT=[Format] [ProviderNo] represents the Provider number that you wish to seach for and the format is either JSON (default) or XML	JSON or XML	n/a
Get Local Providers List	/rest/practice/providers/asJSON This returns a JSON list of the health professionals registered on the local Capricorn. The format is consistant with HL7 v2.3.1 XCN segment Click here to see an example.	JSON	n/a
Send Message	/rest/content/creation/webxml Allows sending a message through the Medical-Objects network. An XML message containing the details is created and then POST-ed to the URL which is then routed through the Medical-Objects network. The only message format supported is XML and returns OK on success, otherwise it returns the reason why the report was unsuccessful.	XML	XML
Provider Search by Name	/rest/provider/lookup/byname?FAMILYNAME=[Surname]&GIVENNAME=[GivenName] This performs a partial search against the Surname and Given names provided and returns a list of the potential matches.	JSON	n/a
Provider Search by ID	MedicalObjectsAssignedProviderNo] This performs a search for a particular provider and returns the details of the provider if found.	JSON	n/a
Provider Search by Postcode	/rest/provider/lookup/bypostcode?POSTCODES=[Comma Seperated list of postcodes] This returns a list of providers that are located at the postcodes provided in the search	JSON	n/a
Provider Search by Postcode with Radius	/rest/provider/lookup/bypostcode/radius?POSTCODES=[Comma Seperated list of postcodes]&RADIUS=[Radius in kilometres] This returns a list of providers that are located at the postcodes provided in the search and also the providers in the area surrounded by that postcode(s)	JSON	n/a

Equator

Supports HTTP 1.1

Uses POST Messages.

The Server accepts encrypted and non-encryted messages but all external access will be PGP/PKI/GNUPG encrypted and signed. The signing key must be enabled on the Server or post will Fail. The server Public key can be obtained directly from the Server. PKI keys are available on LDAP.

The HL7 Messages can be "Classic" HL7 Encoded or XML Encoded (V2.3.1 up). XML in means XML out.

HTTP Request, Method POST

1. Encrypted Message Headers

Connection: keep-alive (this may not be respected :-))

Accept: "application/pgp-encrypted" or "application/pki-encrypted or "application/gnupg-encrypted"

Username: The full PGP/GNUPG/PKI Keyname of the signing Key. No Password.

2. Plain Text Headers (Local LAN connections only)

Connection: keep-alive

Accept: application/hl7

Set username and password as per basic Authentification

PKI/PGP Notes:

The post data is the PGP/PKI/GNUPG encrypted message or plain text message as appropriate.

Will accept Single message or a batch with FHS/BHS/BTS/FTS, no extra characters before or after the message allowed.

PKI Encrypted messages are to be base64 encoded. Will be base 64 encoded on the way out.

As PKI API does not support signed/encryted messages in one ASN.1 wrapper the message is first encypted ('Encoding:Enveloped') and then signed ('Encoding:Signed'). The signer must have a valid PKI Certificate and the message should be encrypted with the target servers encryption site certificate.

For new PKI users the encrytion certificate must be available on HIC LDAP server. Rights are granted on the basis of the signer.

PGP messages to be radix encoded rather than binary.

GNUPG messages should be radix encoded (ie --armor).

The Server response.

Will be PGP/PKI encrypted or plain text depending on the zone. PGP in means PGP out.

The message will be encrypted with the requesting public key and signed by the server key.

For Encrypted messages

ContentEncoding: "pgp-encrypted" or "base64-pki-encrypted" or "gnupg-encrypted"

If the message is not parsable then

ContentEncoding: application/error

In case of an error then the response will be a plain text error message. This will occur if the message fails parsing or the public key of the signer is not registered. If the message is OK but what is requested is not then standard HL7 error handling (Mainly ERR segments) will be used. ie 'application/error' means a connection error. It can be displayed to the user via eg an exception handler and has a multiline nature which Name=Value pairs to give more info, assuming that its not an unauthorised PGP/GNUPG/PKI Key.

The Server URL.

Takes the form of

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/'

e.g. http://203.42.156.38:2000/hl7/

If the message is in PIT format (not desirable) then

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/pit/'

e.g. http://203.42.156.38:2000/hl7/pit/

In the case of a PIT message a HL7 ACK will be returned.

Utility Methods.

1. The PGP/GNUPG Key Name for the Server.

HTTP GET with

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_KEY_NAME'

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_GNUPG_KEY_NAME'

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_PKI_KEY_NAME'

2. The PGP/GNUPG Public Key of the Server.

HTTP GET with

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_PGP_KEY'

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?METHOD=SERVER_GNUPG_KEY'

3. To upload a PGP/GNUPG Public Key for a potential user

HTTP POST with

'http://' + HL7HostName + ':' + inttostr(Port) + '/hl7/admin?' +

'METHOD=CLIENT_KEY_UPLOAD' + ( or 'GNUPG_KEY_UPLOAD')

'&KEYNAME=<PGP Key Name>' +

'&CLIENTNAME=<Text Name of Potential User>' +

'&PHONENUMBER=<Contact Number of Potential User>'

nb: Don't include <>

The Client Public Key is Uploaded as the POST Data.

The key has to be manually validated and a user account created.

The user must know the Key FingerPrint of the Key they are planning to use.

The server will return, a error response if not permitted or some help text if the key has been accepted. The ability to accept keys in this way is an option which can be turned off.

This text gives helpful info which can be displayed to the user.

Server rights:

All users will have a userlevel. The most basic one just allows uploading HL7 ORU Messages (ORU^R01). This is the base right that a valid PKI key permits. In the STF server a valid PKI key permits provider lookup (MFQ^M02). A user can edit their own STF records using MFN^M02 messages.