Difference between revisions of "OHF Bridge Documentation"

Revision as of 03:07, 28 November 2006

This page will try to supply missing documentation problems occurring due to the frequent updates and new requirements we receive from the IHE Connectathon 2007 tests.

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 PatientIdTyp object when referring to patient id, we are not using any longer a simple string. The PatientIdType object contains:

• The idNumber (string) which is the id, 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 it's 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

Some info about the parameters you need to supply in the method calls

• dataSourceId(string): Identity of the participant of the source (maybe your application IP address)
• patientIds(PatientIdType array): Of the involved patients
• patientId(PatientIdType): Of the involved patient
• dataId(string): indicator of the imported/exported data (might be a UUID of a document)
• dataRecipientId (String): who are you sending the data to?

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

• AuditPhiImport
• AuditPhiExport
• AuditActorStartEvent
• AuditActorStopEvent
• AuditUserAuthenticationLoginEvent
• auditUserAuthenticationLogoutEvent

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

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

Audit support in the bridge

The bridge will support the next audit events:

• Actor-Start
• Actor-Stop
• User Authentication
• Query Information
• PHI-import

For more info see the conectathon audit list, and Audit tests.

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.