Difference between revisions of "OHF Bridge Documentation"

Revision as of 13:22, 12 February 2007

After a successful run at the IHE Connectathon 2007, we are currently preparing to issue an official release of OHF and the OHF Bridge. In anticipation of that, we will be updating this page extensively to reflect the finalized API that will be available in the initial public release of the OHF Bridge.

API Clarification

SessionContext

The SessionContext is an object you should send in almost every transaction of the bridge. The SessionContext contains session information needed in order to resolve the resources and parameters the transaction will work with. The SessionContext contains the following:

• User: The user name of the user of the application. Needed for ATNA Auditing
• SessionID: Any string you like. Used in order to synchronize logs in the client and server side. This way you can look up in teh server's log the logs for session ### and match them with the client log.
• RhioName: The name of the RHIO you would like to work with. You may get the list of RHIOs configured in the bridge using RhioConfig[] GetRhios()
• UserApplicationName: The application name (CapMed, OpenEMR, etc). Needed for ATNA Auditing
• UserFacilityName: The facility name (MyClinic, etc). Needed for ATNA Auditing
• ReturnLogLevel: makes the server return log with relevant level if not null and set to one of OFF, FATAL, ERROR, WARN, INFO, DEBUG. See log4j levels for more info.
• UseSecuredConnectionWhenAvaliable: If true, the bridge will use secured connections if they are available in the configurations. If not available the bridge will use unsecured connection.

ResponseType

Almost every call returns a ResponseType or an object inheriting from ResponseType. ResponseType contains the following fields:

• success: true if the transaction was successful, if any element of the transaction failed, return false.
• failMessage: contains a message if the transaction failed
• successMessage: contains a message if the transaction has a success or partial success
• log: returns a string array of logs according to the ReturnLogLevel that was in the SessionContext. There is a limit of the log size it returns, in case the log is too big it is trimmed.
• sessionID: the session id of this transaction (taken from the SessionContext), if the SessionContext had no session id, then it will return the random SessionContext the server used for this transaction.

Sending documents

In beta 3 we've changed the name of the methods to clarify the document submission process and make testing for Connectathon 2007 as easy as possible. This is the only submission option for Connectathon 2007 testing.

• SubmitDocument (use for Connectathon Tests 11746, 11748, 11742, 11743)
  • This service accepts a base 64 encoded, CDA R2 formatted document encoded using the popular Base64, and other necessary XDS Metadata needed for submission. This service will automatically extract XDS Metadata from this document and supplement the metadata with values from a DocumentSubmissionMetadataType object. Successful execution of this request will satisfy Test 11746 and 11742.
  • To replace a document (Test 11748) additionally include th UUID of the parent document you wish to be replaced. This UUID is most easily obtained by issuing a query for the document you want to replace.
  • Instructions for submitting a document over TLS (Test 11743) will be posted soon.
  • Sample:
    • documentType = "CDA" (only this value is accepted now)
    • patientId = "JM19400814" (NamespaceId="HIMSS2005", UniversalId="1.3.6.1.4.1.21367.2005.1.1", UniversalIdType="ISO")

Bridge users must provide the patientID and their sourceID (an OID) along with the codes they feel best describe the submission they are executing. These codes can be fixed, in many cases, based on the kind of application you own. Choices of codes can be found here. A parent document UUID must be provided in the case of document replacement.

AN ASIDE: General comment regarding the "DecodedDocument" field. Please ignore it. We had placed it there to overcome a problem we had with SOAP object translation and we intend to remove it soon.

Searching for Documents

In beta 3 we've changed the name of the methods to clarify the document search process and make testing for Connectathon 2007 as easy as possible.

• QueryDocumentsFind (use for Connectathon Tests 11923, 11936)
  • This function accepts a query request object and a set of query preferences. By adjusting each of these preferences, you can complete the list of tests above.
  • To run a query that will qualify for Test 11923 (FindDocuments Query) you will have to populate a QueryDocumentsRequest1 object which contains a FindDocumentsQueryType object. Be sure that returnReferencesOnly AND the storedQuery preferences are BOTH set to 'false' for the query preferences. For test 11936 (Stored FindDocuments Query), do the same thing, but set storedQuery to 'true'.

• QueryDocumentsGet (use for Connectathon Tests 11927, 11940)
  • This function accepts a query request object and a set of query preferences. By adjusting each of these preferences, you can complete the list of tests above.
  • To run a query that will qualify for Test 11927 (GetDocuments Query) you will have to populate a QueryDocumentsRequest object which contains a GetDocumentQueryType object. Be sure that returnReferencesOnly AND the storedQuery preferences are BOTH set to 'false' for the query preferences. For test 11940 (Stored GetDocuments Query), do the same thing, but set storedQuery to 'true'.
  • Instructions for querying a document over TLS (Test 11741) will be posted soon.

• QueryDocumentsByPatientId (use for Connectathon Tests 11801, 11802, 11949, 11950, 11741)
  • This service queries all documents for a given patient.
  • To complete 11801, populate PatientIdType object, but on the documentQueryPreferencesType be sure that the returnReferencesOnly preference is set to 'true'. To complete 11802, do the same thing, but set returnReferencesOnly to 'false'.
  • To complete 11949, populate PatientIdType object, but on the documentQueryPreferencesType be sure that the returnReferencesOnly AND the storedQuery preferences are BOTH set to 'true'. To complete 11950, do the same thing but set returnReferencesOnly to 'false'.
  • This function may be used to pass tests 11923 and 11936 because it executes a FindDocuments Query under the covers. The same restrictions on the query paramters apply here too.
  • Instructions for querying a document over TLS (Test 11741) will be posted soon.

• RetrieveDocumentByUniqueId and RetrieveDocumentByUUID (use for Connectathon tests 11734 and 11739)
  • This function was previously called 'GetDocumentsByUniqueId' and 'GetDocumentsByUUID' but was changed due to a naming conflict with the IHE query called 'GetDocuments'.
  • Either function can be used to pass 11734 (Retrieve Document).
  • Instructions for retrieving a document over TLS (Test 11739) will be posted soon.

• DateTimeRangeType is used for searching a document with date constraints.
  • There might be more then one DateTimeRangeType in a search. There are five types of DateTimeRangeType distinguished by their AttributeName:
    • creationTime
    • serviceStartTime
    • serviceStopTime
    • submissionTime
    • lastUpdateTime
  • Time/date (To and From) must follow this format: YYYY[[[[MM[DD]]HH]MM]SS]

Patient ID

Note that we are using a PatientIdType object when referring to patient id. We are no longer using a simple string. The PatientIdType object contains:

• The idNumber (string) which is the patient identifier, for example 16edfc6d4bc341a.
• An AssigningAuthorityType which is an object containing the attributes of the AssigningAuthority which contains:
  • namespaceId (string): the namespace ID. This attribute is allowed for PIX/PDQ but its use is prohibited in XDS. The value used for PIX/PDQ for Connectathon is HIMSS2005.
  • universalId (string) : in the Connectathon it will be 1.3.6.1.4.1.21367.2005.3.7
  • universalIdType (string) : This is always ISO
  • useDefaultAssigningAuthority (boolean) : Default is false. If it is true, then in case the AssigningAuthority is empty, the RHIO AssigningAuthority details will be used for the client.

Audit

Description of the parameters you'll see in the audit massages.

• All messages receive a eventOutcome(intiger). The eventOutcome should be one of
  • 0 : Success
  • 4 : Minor failure
  • 8 : Serious failure
  • 12: Major failure; action made unavailable

The methods exposed (which using the above object) are:

• auditQueryEvent(int eventOutcome, String registryID, String queryText) : Method to call that will send a Query Audit Event to the Audit Repository. For use by the XDS Consumer, PIX Consumer and PDQ Consumer.
  • eventOutcome event outcome from AtnaAuditClient
  • registryID Id of the entity that is responsible for answering the query (ie. XDS Registry or the PIX/PDQ Server)
  • queryText complete text of the query issued.

• auditPHIImportEvent(int eventOutcome,String dataSourceId, String patientId[], String importedData): Method to call that will send a PHI Import Audit Event to the Audit Repository. For use by the XDS Consumer, PIX Consumer and PDQ Consumer.
  • eventOutcome event outcome from AtnaAuditClient
  • dataSourceId where the imported data came from (ie. the XDS Registry or the PIX/PDQ server)
  • patientId Patient Id from within imported data
  • importedData exact data or UUID/uniqueId of data imported as a String

• auditPHIExportEvent(int eventOutcome, String dataRecipientId, String exportedDataId, String patientId): Method to call that will send a PHI Export Audit Event to the Audit Repository. For use by the XDS Source and PIX Source
  • eventOutcome event outcome from AtnaAuditClient
  • dataRecipientId where the exported data is going (ie. the XDS Repository or the PIX/PDQ server)
  • exportedDataId UUID/uniqueId of data exported as a String
  • patientId the id of the patient this data pertains to

• auditActorStartEvent(int eventOutcome, String dataRecipientId) : Method to call that will send a Application Start Audit Event to the Audit Repository. For use by all actors.
  • eventOutcome event outcome from AtnaAuditClient
  • dataRecipientId where the exported data is going (ie. the XDS Repository or the PIX/PDQ server)

• auditActorStopEvent(int eventOutcome, String dataRecipientId) : Method to call that will send a Application Stop Audit Event to the Audit Repository. For use by all actors.
  • eventOutcome event outcome from AtnaAuditClient
  • dataRecipientId where the exported data is going (ie. the XDS Repository or thePIX/PDQ server)

• auditPatientRecordReadEvent(int eventOutcome, String patientId) : Method to call that will send a Patient Record Audit Event, which indicates that a READING of a patient record took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • patientId the id of the patient the record pertains to

• auditPatientRecordCreateEvent(int eventOutcome, String patientId) : Method to call that will send a Patient Record Audit Event, which indicates that a CREATING of a patient record took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • patientId the id of the patient the record pertains to

• auditPatientRecordUpdateEvent(int eventOutcome, String patientId)  : Method to call that will send a Patient Record Audit Event, which indicates that a UPDATING of a patient record took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • patientId the id of the patient the record pertains to

• auditPatientRecordDeleteEvent(int eventOutcome, String patientId)  : Method to call that will send a Patient Record Audit Event, which indicates that a DELETING of a patient record took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • patientId the id of the patient the record pertains to

• auditUserAuthenticationLoginEvent(int eventOutcome, String initiatingUserName, String initiatingUserNodeIP, String authenticatingNodeIP) : Method to call that will send a User Authentication Event, which indicates that a LOGIN took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • initiatingUserName the name of the user logging in
  • initiatingUserNodeIP the IP Address of the node the user is logging into
  • authenticatingNodeIP the IP Address of the node that is authenticating the user

• auditUserAuthenticationLogoutEvent(int eventOutcome, String initiatingUserName, String initiatingUserNodeIP, String authenticatingNodeIP) : Method to call that will send a User Authentication Event, which indicates that a LOGIN took place, to the Audit Repository.
  • eventOutcome event outcome from AtnaAuditClient
  • initiatingUserName the name of the user logging in
  • initiatingUserNodeIP the IP Address of the node the user is logging into
  • authenticatingNodeIP the IP Address of the node that is authenticating the user

View Your Logs

We strongly advise that you enable the viewing of OHF Bridge logs via your application. Transaction details as well as transaction payload is recorded there, thus capturing necessary information you will need to verify that you have properly executed a test for Connectathon 2007. You can retrieve OHF Bridge logs, customized for your application, using the GetMyLog function.

Bridge Configurations

So what does the bridge configuration provide?

Lets ask these questions:

• Q: Would the bridge user need to know anything about the domain it wants to play in?

  A: By default, no. The user needs to get the list of RHIOs using the getRhios method and pick one RHIO it wants to work with. The user doesn't have to use the getRhios to do that, if the user has the name of the RHIO from another source it should be enough. The getRhio gives the user the full configuration set of this RHIO including URLs, namespaces etc, but these are just for technical users who might want to inspect the RHIO configuration. The RHIO configuration set may include default values for client namespaces, if the client choose to overwrite them its better.

• Q: Like would it need to know its local assigned domain?

  A: It might be configured in the RHIOs, we did configured these parameters for the Connectathon tests. Please note that in some topologies it is not a good move to configure such cient defaults. For exmple when you have multiple clients. You do want to make them each use its own namespace and not use a default one.

• Q: What about the community affinity domain?

  A: This is not a client default, this is a system configuration that the bridge is (must be) configured with. The user does not need to know it.

• Q: Any of the URLs to the registry or repository? How about audit repository?

  A: None of those. They are all configured in the RHIO configuration set. Please note that there might be a RHIO without one of the servers. For example, a RHIO without an Audit server. In this case the bridge will not send audit messages. If there will be a RHIO without a PIX server, the bridge might be able to submit files and do Audit leaving the user with a need to get the patient ids from somewhere else. A full RHIO might have:

  • Registry (document search)
  • Repository (Document upload)
  • Audit (Audit)
  • PIX (Patient query, upload, update ...)

Configuration on the public online version of the bridge

We have a few specific configurations for NIST and MESA. XYZ Stands for the name of the application/vendor who is doing the test. The following sets are duplicated per vendor and have IP addresses to the vendors MESA PC machine. The latest version of the configuration XML can be found here.

• XYZ MESA consumer port 3600 receiving app MESA_XREF and facility XYZ_HOSPITAL
  • PIX Tests:
    • 10501a and 10501b
    • 10502
    • 10503

• XYZ MESA consumer port 3700 receiving app MESA_XREF and facility XYZ_HOSPITAL
  • PDQ Tests:
    • 11311
    • 11312
    • 11315
    • 11320
    • 11325
    • 11335

• XYZ MESA Source port 3600 receiving application MESA_OP and facility XYZ_HOSPITAL
  • PIX Test:
    • 10512a and 10512b and 10512c

Secured connection

There are two sides to security at the bridge:

• Secured connection between your application and the bridge

  To do this you need to exchange certificates with the bridge once it is configured to communicate via TLS with the clients. In order to reduce the integration barriers we don't include it now in the bridge since it is not needed to pass the MESA/NIST Connectathon tests.

• Secured connection between the bridge and the back end (XDS/PIX servers)

  The bridge configuration already stores the needed secured URLs and certificates. All you need to so is to set the UseSecuredConnectionWhenAvaliable in the session context to true.