OHF XDS Document Source

OHF XDS Document Source

Architecture & API Documentation

Version 0.2.0

API Documentation

The XDS Document Source provides an API for the execution of the following IHE Transactions: ITI-15: Provide and Register Document Set Transaction. The API also provides utility functions for the construction of the payload data for this transaction (a SubmitTransactionData object) as well as the potential for automatic metadata extraction from any particular document type. In the use cases below, we first document the various ways to compose the payload data needed for a Provide and Register Document Set Transaction and then document how to execute this transaction.

Use Case 1 – Adding a Document to the SubmitTransactionData

Joe User, using his EMR Application, wants to submit documents to an XDS Repository. First, he needs to compose a list of documents and corresponding metadata to send. He adds his first document, is returned a reference to the metadata already created and is able to obtain this DocumentEntryType and add any missing fields.

Flow of Execution

API Highlights

The featured method in the above control flow is the SubmitTransactionData.addDocument() method.

Sample Code

Description

The following sample code illustrates how the API user can add a Document to the SubmitTransactionData object, as part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//Create a SubmitTransactionData for a single Provide and Register Document Set 
//Transaction. 
//////////////////////////////////////////////////////////////////////////////// 
SubmitTransactionData txnData = new SubmitTransactionData(); 
//////////////////////////////////////////////////////////////////////////////// 
//Suppose we have an HL7 CDA R2 schema compliant, XML, clinical document we want 
//to submit. Suppose this file is located at “C:/temp/input.xml”. We first need 
//to create a Document object for this file, with the appropriate 
//DocumentDescriptor. The DocumentDescriptor is important because it is used to 
//determine which available DocumentEntryExtractor to run for the given 
//Document. It is strongly recommended to use the DocumentDescriptor constants 
//provided. 
//////////////////////////////////////////////////////////////////////////////// 
Document clinicalDocument = new 
Document("C:/temp/input.xml",DocumentDescriptor.CDA_R2); 
//////////////////////////////////////////////////////////////////////////////// 
//We can now add the document to the SubmitTransactionData object we are 
//composing. XDS DocumentEntry Metadata will be automatically extracted from the 
//Document if a DocumentEntryExtractor for the DocumentDescriptor.CDA_R2 has 
//been made available for the SubmitTransactionData object. If no 
//DocumentEntryExtractor is available, an empty DocumentEntryType is created. In 
//either case the DocumentEntryType is assigned an entryUUID and this is 
//information is returned. 
//////////////////////////////////////////////////////////////////////////////// 
String docEntryUUID = txnData.addDocument(clinicalDocument); 
//////////////////////////////////////////////////////////////////////////////// 
//Now obtain the DocumentEntry created for this clinical document and edit (or 
//verify) the metadata values. 
//////////////////////////////////////////////////////////////////////////////// 
DocumentEntryType docEntry = txnData. getDocumentEntry(docEntryUUID); 
//////////////////////////////////////////////////////////////////////////////// 
// Add the patientId 
//////////////////////////////////////////////////////////////////////////////// 
CX patientId = MetadataFactory.eINSTANCE.createCX(); 
patientId.setIdNumber(“1234567890”); 
patientId.setAssigningAuthorityUniversalId(“1.3.6.1.4.1.21367.2005.1.1”); 
patientId.setAssigningAuthorityUniversalIdType(“ISO”); 
docEntry.setPatientId(patientId); 
//**NOTE: see OHF Metadata Model Documentation for more examples on editing XDS 
//Metadata 

Use Case 2 – Adding Submission Set Metadata to the SubmitTransactionData

Joe User now wants to add Submission Set Metadata values.

Flow of Execution

API Highlights

The featured method in the above control flow is the SubmitTransactionData.getSubmissionSet() method.

Sample Code

Description

The following sample code illustrates how the API user can edit the SubmissionSet metadata for the SubmitTransactionData object, as part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//Now obtain the SubmissionSet created for this SubmitTransactionData and edit 
//(or verify) the metadata values. Assume we have an already constructed 
//SubmitTransactionData object called ‘txnData’ as in 3.1.3.2. 
//////////////////////////////////////////////////////////////////////////////// 
SubmissionSetType subset = txnData.getSubmissionSet(); 
//////////////////////////////////////////////////////////////////////////////// 
//Set the contentTypeCode on the SubmissionSet 
//////////////////////////////////////////////////////////////////////////////// 
CodedMetadataType contentTypeCode = 
MetadataFactory.eINSTANCE.createCodedMetadataType(); 
contentTypeCode.setCode(“Consult”); 
contentTypeCode.setDisplayName(“Consult”); 
contentTypeCode.setSchemeName(“Connect-a-thon contentTypeCodes”); 
subSet.setContentTypeCode(contentTypeCode); 
//**NOTE: see OHF Metadata Model Documentation for more examples on editing XDS 
//Metadata 

Use Case 3 – Adding Folders to the SubmitTransactionData

Joe User now wants to add a Folder to the submission he is composing. He additionally wants to place the document he has added in the newly created folder.

Flow of Execution

API Highlights

The featured methods in the above control flow are the SubmitTransactionData.addFolder() and SubmitTransactionData.addDocumentToFolder() methods.

Description =

The following sample code illustrates how the API user can add and edit the created Folder for the SubmitTransactionData object as well as place documents in this folder, as an optional part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//Now add a Folder to this SubmitTransactionData and edit (or verify) the 
//metadata values. Assume we have an already constructed SubmitTransactionData 
//object called ‘txnData’.
//////////////////////////////////////////////////////////////////////////////// 
String folderEntryUUID = txnData.addFolder(); 
FolderType folder = txnData.getFolder(folderEntryUUID); 
//////////////////////////////////////////////////////////////////////////////// 
//Set a code the on the Folder 
//////////////////////////////////////////////////////////////////////////////// 
CodedMetadataType code = MetadataFactory.eINSTANCE.createCodedMetadataType(); 
code.setCode(“General Medicine”); 
code.setDisplayName(“General Medicine”); 
code.setSchemeName(“Connect-a-thon codeList”); 
folder.setContentTypeCode(code); 
//**NOTE: see OHF Metadata Model Documentation for more examples on editing XDS 
//Metadata 
//////////////////////////////////////////////////////////////////////////////// 
//Add the document to this folder. 
//////////////////////////////////////////////////////////////////////////////// 
txnData.addDocumentToFolder(docEntryUUID, folderEntryUUID); 

Use Case 4 – Loading XDS Metadata from Files into the

SubmitTransactionData Joe User now has a clinical document and “pre-cooked” metadata in an ebXML formatted file that he wants to add, as is, to the growing SubmitTransactionData object.

Flow of Execution

API Highlights

The featured method in the above control flow is the SubmitTransactionData.loadDocumentWithEbXMLMetadata() method. This is described below in greater detail. The API also allows for the replacement of the Submission Set metadata with data contained in a file or an in-memory ebXML model. Additionally the API allows for the addition of folders to the SubmitTransactionData object using data from a file or an in-memory ebXML model. The process of doing so is similar to loading documents and corresponding, “pre-cooked” Document Entry metadata and will not be further elaborated on in this document.

Sample Code

Description

The following sample code illustrates how the API user can add a Document and “pre-cooked” DocumentEntry metadata to the SubmitTransactionData object, as part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
// Assume we have a SubmitTransactionData object, ‘txnData’. 
// Suppose we have an HL7 CDA R2 schema compliant, XML, clinical 
//document we want to submit. Suppose this file is located at 
//“C:/temp/input2.xml”. Suppose also we have DocumentEntry metadata in ebXML 
//format for this CDA R2 clinical document located at “C:/temp/metadata2.xml”. 
//////////////////////////////////////////////////////////////////////////////// 
Document clinicalDocument2 = new 
Document("C:/temp/input2.xml",DocumentDescriptor.CDA_R2); 
File docEntryEbXMLFile = new File ("C:/temp/metadata2.xml"); 
FileInputStream fis = new FileInputStream(docEntryEbXMLFile); 
String docEntryUUID_2 = txnData.loadDocumentWithEbXMLMetadata(clinicalDocument2, fis); 
//////////////////////////////////////////////////////////////////////////////// 
//Now obtain the DocumentEntry created for this clinical document and edit (or 
//verify) the metadata values. 
//////////////////////////////////////////////////////////////////////////////// 
DocumentEntryType docEntry2 = txnData.getDocumentEntry(docEntryUUID_2); 
//**NOTE: see OHF Metadata Model Documentation for more examples on editing XDS 
//Metadata 

Use Case 5 – Deleting Documents and/or Folders from the

SubmitTransactionData Joe User decides he wants to delete a folder or a document from the submission he is composing.

Flow of Execution

API Highlights

The featured methods in the above control flow are the SubmitTransactionData.deleteDocumentFromFolder(), SubmitTransactionData.deleteFolder(), and SubmitTransactionData.deleteDocument() methods.

Sample Code

Description

The following sample code illustrates how the API user can delete current Documents and Folders from the SubmitTransactionData object, as an optional part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//Assume we have an already constructed SubmitTransactionData //object called 
//‘txnData’. Assume the folder and document we want to delete are 
//those referenced by ‘folderEntryUUID’ and ‘docEntryUUID’. 
//////////////////////////////////////////////////////////////////////////////// 
// disassociate the document with the folder 
txnData.deleteDocumentFromFolder(docEntryUUID, folderEntryUUID); 
// remove the folder from the submission 
txnData.deleteDocumentFromFolder(docEntryUUID, folderEntryUUID); 
// remove the document from the submission 
txnData.deleteDocumentFromFolder(docEntryUUID, folderEntryUUID); 

Use Case 6 – Adding Existing Documents and/or Folders to the

SubmitTransactionData Joe User decides he wants to add a document to an existing folder or an existing document from the submission he is composing. An “existing” document or folder is one that already exists in the XDS Registry because it was registered there by a prior Provide and Register Document Set transaction.

Flow of Execution

API Highlights

The featured methods in the above control flow are the SubmitTransactionData.addExistingFolder(), SubmitTransactionData.addDocumentToFolder(), and SubmitTransactionData.addExistingDocument() methods.

Sample Code

Description

The following sample code illustrates how the API user can add existing Documents and Folders to the SubmitTransactionData object, as an optional part of the process for composing data needed for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//Assume we have an already constructed SubmitTransactionData object called 
//‘txnData’. Assume the existing folder and document we want to 
//add are those referenced by ‘folderEntryUUID_Existing’ and 
//‘docEntryUUID_Existing. We obtained these uuids by doing a query or saving the 
// ids in a local cache. Additionally, we want to place the document referenced 
// by ‘docEntryUUID_2’ into the existing folder. 
//////////////////////////////////////////////////////////////////////////////// 
// add the existing folder 
txnData.addExistingFolder(docEntryUUID, folderEntryUUID_Existing); 
// add the document referenced by ‘docEntryUUID_2 to the existing folder  
txnData.addDocumentToFolder(docEntryUUID_2, folderEntryUUID_Existing); 
// add the existing document to the submission set 
txnData.addExistingDocument(docEntryUUID_Existing); 

Use Case 7 – Executing the Provide and Register Document Set

Transaction Finally, Joe User is ready to submit the SubmitTransactionData he has so carefully composed. (NOTE: if we follow the sample code, collectively, we see that what remains of Joe’s submission is the submission set metadata composed, the document with corresponding metadata added. and the references to an existing folder and an existing document added).

Flow of Execution

API Highlights

The featured method in the above control flow is the Source.submit() method.

Sample Code

Description

The following sample code illustrates how the API user can submit documents for the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//If an instance does not already exist, create an instance of the XDS Source 
//and provide the XDS Repository url and port. Also enable transaction auditing. 
//////////////////////////////////////////////////////////////////////////////// 
String repositoryURL = “http://my.repository.url:8080”; 
Source source = new Source(repositoryURL); 
//////////////////////////////////////////////////////////////////////////////// 
//Assume we have a populated SubmitTransactionData object, ‘txnData’, as we left 
//it. Now we simply submit the document and the metadata it contains. 
//////////////////////////////////////////////////////////////////////////////// 
try { 
    source.submit(txnData, "JOE USER"); 
} catch (SourceException e) { 
    System.out.println("Source.submit failed", e); 
} catch (Throwable th) { 
    System.out.println("Unexpected error", th); 
} 

Use Case 7 – Executing the Provide and Register Document Set

Transaction for Document Replacement Finally, Joe User is ready to submit the SubmitTransactionData he has so carefully composed. (NOTE: if we follow the sample code, collectively, we see that what remains of Joe’s submission is the submission set metadata, the document with corresponding metadata added. and the references to an existing folder and an existing document added). However, he wants to replace a document on that already exists in the XDS Registry with the new document he has in this submission set.

Flow of Execution

Sample Code

Description

The following sample code illustrates how the API user can replace a document in the XDS Registry using the Provide and Register Document Set Transaction.

Code

//////////////////////////////////////////////////////////////////////////////// 
//If an instance does not already exist, create an instance of the XDS Source 
//and provide the XDS Repository url and port. Also enable transaction auditing. 
//////////////////////////////////////////////////////////////////////////////// 
String repositoryURL = “http://my.repository.url:8080”; 
Source source = new Source(repositoryURL); 
//////////////////////////////////////////////////////////////////////////////// 
//Assume we have a populated SubmitTransactionData object, ‘txnData’.
// Assume the document we want to replace is referenced by 
//‘docEntryUUID_Parent. We obtained this uuids by doing a query or saving the 
// id in a local cache. The document we want to replace it with is referenced by 
//‘docEntryUUID_2’. 
//////////////////////////////////////////////////////////////////////////////// 
txnData.getDocumentEntry(docEntryUUID_2).setParentDocumentRelationship( 
     ParentDocumentRelationshipType.RPLC_LITERAL); 
     txnData.getDocumentEntry(docEntryUUID_2).setParentDocumentId(docEntryUUID_Parent 
); 
//////////////////////////////////////////////////////////////////////////////// 
// Now we simply submit the document and the metadata it contains. 
//////////////////////////////////////////////////////////////////////////////// 
try { 
     source.submit(txnData, "JOE USER"); 
} catch (SourceException e) { 
     System.out.println("Source.submit failed", e); 
} catch (Throwable th) { 
     System.out.println("Unexpected error", th); 
}

Security

Node Authentication

Node Authentication is accomplished using Java keystores. For more information regarding the creation of keystores and truststores in Java see the OHF ATNA Agent documentation. Once you have created your java keystore containing your private key and a truststore containing all keys of your trusted partners, simply run the OHF XDS Source with the following JVM arguments:

-Djavax.net.ssl.keyStore=<location of your keystore file> 
-Djavax.net.ssl.keyStorePassword=<password to your keystore file> 
-Djavax.net.ssl.trustStore=<location of your truststore file> 
-Djavax.net.ssl.trustStorePassword=<password to your truststore file> 

Auditing

All auditing events surrounding the OHF XDS Source transaction is taken care of by this plugin. Auditing is enabled by default and audit messages, by default, are sent to syslog://lswin10.dfw.ibm.com:515.

To disable auditing for all OHF events call the following:

AtnaAgentFactory.getAtnaAgent().setDoAudit(false); 

To switch the url of the Audit Record Repository to which the audit events are being sent, call the following:

AtnaAgentFactory.getAtnaAgent().setAuditRepository(new URI( “syslog://new.audit.url));. 

To re-enable auditing for all OHF events, call the following:

AtnaAgentFactory.getAtnaAgent().setDoAudit(true); 

To create your own auditing message for application specific events, please see the OHF ATNA Agent documentation.

Auditing Example Code

Description

The following sample code illustrates how the above auditing commands can be used in conjunction with the OHF XDS Source.

Code

//////////////////////////////////////////////////////////////////////////////// 
//If an instance does not already exist, create an instance of the XDS Source 
//and provide the XDS Repository url and port. Also enable transaction auditing. 
//////////////////////////////////////////////////////////////////////////////// 
String repositoryURL = “http://my.repository.url:8080”; 
Source source = new Source(repositoryURL); 
//////////////////////////////////////////////////////////////////////////////// 
//Switch Audit Record Repository end point 
//////////////////////////////////////////////////////////////////////////////// 
String auditURL = “syslog://my.audit.url:515”; 
AtnaAgentFactory.getAtnaAgent().setAuditRepository(new URI(auditURL)); 
//////////////////////////////////////////////////////////////////////////////// 
//Assume we have a populated SubmitTransactionData object, ‘txnData’, as we left 
//it. Now we simply submit the document and the metadata it contains. 
//////////////////////////////////////////////////////////////////////////////// 
try { 
     source.submit(txnData, "JOE USER"); 
} catch (SourceException e) { 
     System.out.println("Source.submit failed", e); 
} catch (Throwable th) { 
     System.out.println("Unexpected error", th); 
} 
//Turn off auditing for a submission to a different repository (suppose we 
//want to do this … for some reason). 
AtnaAgentFactory.getAtnaAgent().setDoAudit(true); 
String otherRepository = “http://other.repository.url:8080” 
source.setRepositoryURL (otherRepository); 
try { 
     source.submit(txnData, "JOE USER"); 
} catch (SourceException e) { 
     System.out.println("Source.submit failed", e); 
} catch (Throwable th) { 
     System.out.println("Unexpected error", th); 
}

Configuration

The following is a list of configurable aspects:

• Java properties for TLS communication (set the following as JVM arguments):

-Djavax.net.ssl.keyStore=<location of your keystore file> 
-Djavax.net.ssl.keyStorePassword=<password to your keystore file> 
-Djavax.net.ssl.trustStore=<location of your truststore file> 
-Djavax.net.ssl.trustStorePassword=<password to your truststore file> 

• Audit Record Repository url and port:

String auditURL = “syslog://my.audit.url:515”; 
AtnaAgentFactory.getAtnaAgent().setAuditRepository(new URI(auditURL)); 

• Enable/Disable auditing flag

AtnaAgentFactory.getAtnaAgent().setDoAudit(true); // enable 
AtnaAgentFactory.getAtnaAgent().setDoAudit(false); // disable 

• Initiating user ID, for auditing (an API parameter on each transaction)
• XDS Registry url and port (an API parameter on the constructor of the OHF XDS Source)
• Logging is configurable.

Debugging Recommendations

The XDS Source uses Apache Log4j. If you are experiencing bugs related to the Source, you may enable debug level logging by adding the following category to your log4j XML configuration file.

<category name="org.eclipse.ohf.ihe.xds.source"> 
     <priority value="debug" /> 
</category > 

For more information about Log4j please see: http://logging.apache.org/log4j/docs/

For an example log4j XML configuration file and to see how it is loaded at run time see 'org.eclipse.ohf.ihe.xds.source/resources/conf/submitTest_log4j.xml' and 'org.eclipse.ohf.ihe.xds.source/src_tests/SubmitTest.java', respectively. These can be obtained by downloading the plugin org.eclipse.ohf.ihe.xds.source from the Eclipse CVS technology repository.

Pending Integration and API changes

Below is a laundry list of anticipated changes to the XDS Source:

1. Support for DSG – Enabling submission of digitally signed documents also requires changes to the SubmitTransactionData object. We are awaiting resolution to internal IHE discussions on how to test DSG at Connectathon 2007 or 2008 before considering these modifications.
2. We anticipate supporting the new web-service version of the Provide and Register Transaction that is in development for the 2007-2008 season.