Skip to main content

Routed CDA document – Business Acknowledgement

This scenario illustrates the case where the sender elects to receive a business acknowledgement. In this case the ITK API allows the setting of a message property to request the return of a Business Acknowledgement.

It is important to note that the Business Acknowledgement is a Routed messages and therefore requires an Infrastructure Acknowledgement itself, making this is the most complex of the ITK message patterns.

Page contents

Sender view

From the Sender perspective this is very similar to the previous CDA scenario, except that the sender requests a Business Acknowledgement.

The sending application must also provide the capability to receive and acknowledge the Business Acknowledgement.

ITK Router view

The ITK Router is not affected by the request for a Business Acknowledgement. This is simply forwarded as an attribute of the message.

Receiver view

The Receiver at the infrastructure level – essentially within the Reference Implementation – is not affected by the request for a Business Acknowledgement. This is an application responsibility and must be handled by the application code.

The application will construct the Business Acknowledgement (according to the schema in the ITK Core Pack) and send back to the originator ITK address using the standard sendAsync method of the API.

Request message (get example)

The Business Acknowledgement is requested in the handling specification section.

[code lang=""xml""]<br /><itk:header<br />service="urn:nhs-itk:services:201005:SendCDADocument-v2-0" trackingid="A40BF902-AEDE-4ABC-94A1-2623C9D3E357"><br /><itk:addresslist><br /><itk:address uri="urn:nhs-uk:addressing:ods:TESTORGS:CDAEMULATORLOCAL"/><br /></itk:addresslist><br /><itk:auditIdentity><br /><itk:id uri="urn:nhs-uk:identity:ods:R59:oncology"/><br /></itk:auditIdentity><br /><itk:manifest count="1"><br /><itk:manifestitem id="uuid_NJ3" mimetype="text/xml"<br />profileid="urn:nhs-en:profile:nonCodedCDADocument-v2-0"/><br /></itk:manifest><br /><itk:senderAddress uri="urn:nhs-uk:addressing:ods:R59:oncology"/><br /><itk:handlingSpecification><br /><itk:spec key="urn:nhs:itk:ns:201005:ackrequested" value="true"/><br /></itk:handlingSpecification><br /></itk:header>[/code]

Response message (get example)

The Business Acknowledgement is a Core Message contained within the Distribution Envelope.

[code lang=""xml""]<br /><itk:DistributionEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><br /><%%KEEPWHITESPACE%%> <itk:header service="urn:nhs-itk:services:201005:SendBusinessAck-v1-0" trackingid="2A966984-4 ...<br /><%%KEEPWHITESPACE%%> <itk:addresslist> ... </itk:addresslist><br /><%%KEEPWHITESPACE%%> <itk:auditIdentity> ... </itk:auditIdentity><br /><%%KEEPWHITESPACE%%> <itk:manifest count="1"><br /><%%KEEPWHITESPACE%%> <itk:manifestitem id="uuid_CDE4A7DB-979B-4D15-A7F3-53F247B4BAA7"<br /><%%KEEPWHITESPACE%%> mimetype="text/xml" profileid="urn:nhs-en:profile:ITKBusinessAcknowledgement-v1-0"/><br /><%%KEEPWHITESPACE%%> </itk:manifest><br /><%%KEEPWHITESPACE%%> <itk:senderAddress uri="urn:nhs-uk:addressing:ods:TESTORGS:ORGA"/><br /><%%KEEPWHITESPACE%%> </itk:header><br /><%%KEEPWHITESPACE%%> <itk:payloads count="1"><br /><%%KEEPWHITESPACE%%> <itk:payload id="uuid_CDE4A7DB-979B-4D15-A7F3-53F247B4BAA7"><br /><%%KEEPWHITESPACE%%> <v3:BusinessResponseMessage xmlns:v3="urn:hl7-org:v3"><br /><%%KEEPWHITESPACE%%> <v3:id root="CDE4A7DB-979B-4D15-A7F3-53F247B4BAA7"/><br /><%%KEEPWHITESPACE%%> <v3:creationTime value="201302051101"/><br /><%%KEEPWHITESPACE%%> <v3:interactionId extension="urn:nhs-itk:interaction:ITKBusinessAcknowledgement-v1-0"<br /><%%KEEPWHITESPACE%%> root="2.16.840.1.113883.2.1.3.2.4.12"/><br />[/code]

How it all happens - step 1

The sending application builds a SimpleMessage and populates the business payload with the CDA Document in serialized form. The application requests a business acknowledgement by adding a handling specification into the message properties.The full source code for the Hello World CDA example can be seen here.

[code lang=""java""]<br />// Create the message<br />ITKMessage msg = new SimpleMessage();<br />msg.setBusinessPayload(docText);<br />...<br />// Set the message properties<br />mp.setServiceId("urn:nhs-itk:services:201005:SendCDADocument-v2-0");<br />...<br />// Request the business ack.<br />if (businessAckRequired.equalsIgnoreCase("Y")){<br />mp.addHandlingSpecification(ITKMessageProperties.BUSINESS_ACK_HANDLING_SPECIFICATION_KEY, "true");<br />}<br /><br />// Create the sender<br />ITKMessageSender sender = new ITKMessageSenderImpl();<br />...<br />// Send this message Asynchronously - return is void.<br />sender.sendAsync(msg);<br />[/code]

Step 2

(Sending RI)

The send Async API builds handling specifications into the Distribution Envelope on the wire as shown in this example.

[code lang=""java""]<br /><itk:header<br />service="urn:nhs-itk:services:201005:SendCDADocument-v2-0" trackingid="A40BF902-AEDE-4ABC-94A1-2623C9D3E357"><br /><itk:addresslist><br /><itk:address uri="urn:nhs-uk:addressing:ods:TESTORGS:CDAEMULATORLOCAL"/><br /></itk:addresslist><br /><itk:auditIdentity><br /><itk:id uri="urn:nhs-uk:identity:ods:R59:oncology"/><br /></itk:auditIdentity><br /><itk:manifest count="1"><br /><itk:manifestitem id="uuid_NJ3" mimetype="text/xml"<br />profileid="urn:nhs-en:profile:nonCodedCDADocument-v2-0"/><br /></itk:manifest><br /><itk:senderAddress uri="urn:nhs-uk:addressing:ods:R59:oncology"/><br /><itk:handlingSpecification><br /><itk:spec key="urn:nhs:itk:ns:201005:ackrequested" value="true"/><br /></itk:handlingSpecification><br /></itk:header><br />[/code]

Step 3

The message properties, including the handling specifications, are deserialised by the Reference Implementation and presented back to the receiving application handler as they were built by the sender.

Where the Business Ack handling specification is present then the application handler knows that it must return a business acknowledgement.

When this happens will depend on the business process of the receiver and the agreement between sender and receiver as the business acknowledgement is a generic wrap designed to contain content as agreed locally.

Last edited: 12 August 2021 10:36 am