ReferralNet Services Developer Section

The ReferralNet messaging service implements at its core the IHE Integration Profile referred to as XDR (for Cross-Enterprise Document Reliable Interchange), and is focused on providing a standards-based specification for managing the interchange of documents that healthcare enterprises (anywhere from a private physician to a clinic to an acute care in-patient facility) have decided to explicitly exchange using a reliable point-to-point network communication. This also enables better interoperability between Electronic Health Records (EHRs), Personal Health Records (PHRs) and other Healthcare IT Systems.

  • XDR provides a reliable and automatic transfer of documents and metadata for one patient between EHR systems even in the absence of an XDS infrastructure.
  • XDR supports the re-use of the Provide and Register Set transaction-b with Web Services as transport.
  • XDR is document format agnostic, supporting the same document content as XDS and XDM.
  • XDR defines no new metadata or message formats. It leverages XDS metadata with emphasis on patient identification, document identification, description, and relationships.

An interchange of documents can be associated a context through the allocation of classifications at both coarsely and finely grained levels.

Through the use of the XDR/XDS integration profile, it is possible to reliably interchange documents encoded using additional health standards to specify the structure and semantics of a clinical document, such as the Clinical Document Architecture (CDA) specification.

Overview

The ReferralNet messaging service provides a simple set of operations to the developer that supports the sending and receiving of messages as well as integrated transformation and templating functionality.

Operations

All SOAP operations are authenticated against the ReferralNet user directory.

Operation Description
AddAllowedAttachmentTypesAdd a service category to a ReferralNet user
DeleteDocumentSetPhysically deletes the message document payload, logically deletes the message entity.
FindMemberUsed to locate registered ReferralNet members, supports email or name search.
FindRecipientByEmailSearch for a recipient in which to send the referral.
FindRecipientByNameSearch for a recipient in which to send the referral.
FindRecipientByUIDReturn recipient details if their unique identifier is known.
FindRecipientByEIDFind a user by EID and return the translated SMD ID. Can be used to determine if the message is to be sent by ReferralNet API or SMD API
FindRecipientNaturalUses the organic / natural search algorithm to locate a recipient in which to send the message. This should be your search operation of choice as it is the most flexible, acutely tuned to the ReferralNet and integrated 3rd party directories, and is constantly being extended to support wildcards and other useful search notations.
FindRecipientByCertificateEmailSearch for a recipient in which to send the referral.
FindRecipientByCertificateSerialSearch for a recipient in which to send the referral.
InviteUsed to formally invite a colleague to join the ReferralNet community.
ListAllowedAttachmentTypesRetrieves the list of service categories of a ReferralNet user.
ListAttachmentTypesRetrieves the list service categories.
ListDocumentSetsA bi-directional, light weight method that enables you to enumerate messages present in your inbox. This is the method you use to check for the presence of new messages.
MarkDocumentSetEventProvides the ability to set custom transport events against a specific document set. If your application has the requirement to provide more transport events in addition to the standard READ and READ FAILURE events (SCHEDULED, ASSIGNED etc), then this is the method that provides you that ability.
MarkDocumentSetReadRegister a successful READ event against a specific DocumentSet.
MarkDocumentSetReadFailureRegister a READ exception event against a specific DocumentSet.
MarkDocumentSetReadFailureExRegister a READ exception event against a specific document set and supply supporting information.
ProvideAndRegisterDocumentSetBThis key operation is used to send a message to an identified recipient.
RemoveAllowedAttachmentTypesRemoves services categories from a ReferralNet user.
RetrieveClassificationsRetrieves a list of registered, active DocumentSet classification
RetrieveDocumentSetRetrieves a specified document set based on a supplied UID.
RetrieveDocumentSetEventsRetrieves all auditable events associated to a specified DocumentSet.
RetrieveDocumentSetMetaRetrieves only the metadata of a specific document set, excluding the actual payloads. This is particularly useful when you wish to introspect a message in your inbox without incurring the cost of retrieving the actual payload(s) within the document set. It may well be that you do not wish to retrieve the message at all due to it containing payload formats that you do not support. In which case you could dismiss the message from your inbox.
RetrieveEmailServersRetrieves a list of email servers used by the ReferralNet client.
RetrieveMemberPublicKeysRetrieves the specified members' X.509 public keys from the associated Certificate Authority (CA). This ignores the message forwarding option if it has been enabled against the specified users account.
RetrieveRecipientPublicKeysRetrieves the specified recipients' X.509 public keys from the associated Certificate Authority (CA).
RetrieveRecipientTemplatesRetrieves a list of summarised templates associated to a specified recipient.
RetrieveTransformsRetrieves a list of transforms associated to the specified urn.
RetrieveTemplateArchiveRetrieves a specified recipient template archive, this is packaged as a ZIP archive.
RetrieveVersionRetrieves the current version of the messaging service.
RevokeDocumentSetRevokes / cancels a message, useful if you accidentally addressed a message to the wrong recipient.
TransformDocumentSetApply a specific transformation against a supplied DocumentSet.
ValidateMemberValidates a ReferralNet members' credentials and associated account status.

Classifications

There are two levels of classification within a ReferralNet message, the 1st being the classification applied to the message as a whole which we call the RegistryPackage, the 2nd being the classification of each individual document within the package, which we call the ExtrinsicObject.

RegistryPackage

A collection of documents submitted together is termed a RegistryPackage.

UIDDescriptionDefault
urn:refnet:referralA standard referral context with patient XML attachment and an associated HTML body. No
urn:refnet:legacy-referralA standard referral context that is backward compatible with the earlier version of the ReferralNet desktop clientNo
urn:refnet:secure-messageA simple secure message context, if the nodeRepresentation property is not set, the RegistryPackage is inferred to be of this type.Yes
urn:refnetinternal:read-receiptInternal message sent when a message is read by the recipient. Generally not displayed to the user directlyNo
urn:nheta:e-referralA GP and Specialist / Critical Care Referral conformant with Version 1.0 of the NHETA Data Content Specifications.No
urn:refnet:template A pre-defined recipient template. No
urn:sonic:pathology-result A HL7 pathology result message from Sonic HealthCare No

ExtrinsicObject

ExtrinsicObjects provide metadata that describes submitted content whose type is not intrinsically known to the recipient and therefore must be described by means of additional attributes (e.g., mime type). In essence it is semantically similar to the representation of a document within a folder.

UIDDescriptionDefault
urn:refnet:patientA data island that contains demographic patient information, the mime type of the document dictates the format.No
urn:refnet:bodyA document reflecting the main body of the document set.No

Common Sequence of Events

Explanatory Notes

  1. The sending actor first locates the recipient using the ReferralNet Provider Directory Adapter.
  2. The sending actor then retrieves a key (certificate) using the ReferralNet PKI Adapter.
  3. The sending node then signs and encrypts the payload, finally posting it to the ReferralNet messaging service.
  4. The ReferralNet messaging service then posts a notification that the message is available.
  5. The receiving node authenticates to the ReferralNet messaging service and checks for any pending messages.
  6. The receiving node retrieves pending messages and processes them and sets the status of the message.
  7. The receiving node dismisses the message (and notification) (iterative).

ReferralNet Templating

The ReferralNet service supports a dynamic templating model and is based on HTML forms technology. Through the use of this standard, it allows the owner of the template to design, implement and publish forms based on their business requirements using their own development resources.

Packaging HL7 REF I12 with PDF Report

ReferralNet requires specific packaging for HL7 REF I12 messages with a PDF report. Following are the packaging instructions:

  • Set the message classification to: "urn:refnet:referral-pdf-zip"
  • Set the following message based slots:
    • "generated-by" to "<organization name>"
    • "urn:refnet:recipient" to fully qualified recipient userId e.g. "urn:refnet:damong"
  • Create a .zip file with the .hl7 file with in it – add as an attachment to the message
  • Set the following attachment properties:
    • Content-type: application/zip
    • Slots:
      • "urn:refnet:filename" to desired filename of attachement
    • Make sure that the attachment is encrypted

The minimum required for such an HL7 is (not the exhaustive list) :

  • MSH – sending facility (name of sender), receiving facility (username)
  • PID – Patient name and DOB
  • PRD – Referring and Referred to provider names
  • PV1 – patient class, receiving provider (id, lastname, firstname, title)
  • Make sure that the embedded pdf is set to "ED" (Encapsulated Data) and the observation identifier is "PDF^Display format in pdf^AUSPDI"

Frequently Asked Questions

Where is the best place to start?

Consuming the ReferralNet WSDL from within your technology stack is one way, using a test tool is another.

In order to engage with the ReferralNet service, you will first need to register as a user, for development you will need to register against our staging environment.

What authentication mechanism does the ReferralNet Messaging service use?

ReferralNet supports the Web Services Security, UsernameToken Profile 1.1 as its primary authentication scheme.

Does ReferralNet run over SSL?

Yes, the ReferralNet services can only be engaged over HTTPS, its WS-Policy can be found incorporated into the WSDL.

Does the service throw SOAP faults?

The ReferralNet services throws SOAP faults for WS-Security related errors only, beyond the authentication layer each operation returns a RegistryResponse object where among other things a response status attribute can be examined.

How does ReferralNet handle the signing and encipherment of data?

The ReferralNet messaging service always enforces transport encryption, but is agnostic in the use of message encryption models, this means it supports pretty much any scheme, proprietary or otherwise, including the NHETA mandated XML Secured Profile specification.

The message encryption model is dictated by the specification associated to its classification which would normally include associated XML schema and optionally, extended metadata provisioned through the slot mechanism. The method of denoting whether a document is encrypted is to set the isOpaque property of the ExtrinsicObject to true, with an optional slot specifying the encryption model used. The default method of payload protection if not otherwise specified is Enveloped Signed CMS/PKCS#7.

What is the best analogy for the XDR DocumentSet?

Probably the most widely used analogy is that of the RegistryPackage being similar to a folder / directory on disk, the Extrinsic objects being the file descriptors of the files within the folder and the actual document objects reflecting the actual payload of each file.

How do I obtain the digital certificates of the recipient I am sending a message to, so I can encrypt the documents with their public key?

The ReferralNet messaging service provides the RetrieveRecipientPublicKeys SOAP operation for just this purpose, you need to only supply the identifier of the target recipient retrieved from a previous call of the FindRecipientByName, FindRecipientByEmail or FindRecipientNatural operations and the service will retrieve the public keys from the respective certificate repository.

Is there a way of ReferralNet alerting me to the arrival of a new message into its repository so I can fetch it rather than poll?

Yes, If you use a combination of both the ReferralNet email notification events and web service invocation you can avoid polling altogether. A nice benefit of using email for the unsolicited delivery of events is that it is a firewall friendly mechanism.

Interop

There is a registered interoperability issue with Microsofts' Windows Communication Foundation (WCF), it currently does not conform to the "Web Services Security, UsernameToken Profile 1.1, OASIS Standard Specification, 1 February 2006", see related links below.

Web Service Test Tools

Useful tools that facilitate a quick test run of our services without any development effort are:

Code samples

 
dev/start.txt · Last modified: 2017/08/16 06:58 (external edit)