1      Introduction

This document gives an overview of the i2b2 common headers for both request and response XML messages between i2b2 cells in the i2b2 hive.

1.1   The i2b2 Hive

The Informatics for Integrating Biology and the Bedside (i2b2) is one of the sponsored initiatives of the NIH Roadmap National Centers for Biomedical

Computing (http://www.bisti.nih.gov/ncbc/).  One of the goals of i2b2 is to provide clinical investigators broadly with the software tools necessary to collect and manage project-related clinical research data in the genomics age as a cohesive entity, a software suite to construct and manage the modern clinical research chart.  The i2b2 hive is a set of cells or modules that have a common messaging protocol that allow the cells to interact using web services and XML messages.

1.2   i2b2 Messaging Overview

All cells in the i2b2 hive must communicate using standard i2b2 XML messages.  This message specifies certain properties that are common to cells and essential to the administration tasks associated with sending, receiving and processing messages.  All requests are sent using a <request> tag and responses are returned using a <response> tag.  The same <message_header> tag is used for both.  The <request_header> is used for requests but may optionally be echoed back in the response.  The response must include a <response_header>.  The XSD specification of the i2b2 message permits individual cells to add cell-specific XML in the <message_body> tag.  This cell-specific XML need not extend the i2b2 message schema since the i2b2 schema will allow insertion of tags from any namespace into the <message_body> tag.  The following table illustrates the basic top-level elements contained within the request and response messages.

The i2b2 XML schema consists of three XSD files:

 

• xsd

This schema is not used directly to create i2b2 messages, but is included in the i2b2_request.xsd and the i2b2_response.xsd.  It defines the <message_header> tag.

 

• xsd

This schema is used for validating i2b2 request messages.  It defines the <i2b2:request> tag, which includes the <message_header> tag.

 

• xsd

This schema is used for validating i2b2 response messages.  It defines the <i2b2:response> tag, which includes the <message_header> tag.

 

The i2b2 <message_header>, <request_header> and <response_header> are described in this document. For descriptions of cell-specific content of the

<message_body>, please refer to the documents of the specific i2b2 cells.  

2      i2b2 Messaging Detail

2.1   Use Cases

All i2b2 cells must satisfy one specific use case which is to communicate.  The specifics types of communication are defined by each cell.  Any client of an i2b2 cell must communicate by sending a message to the cell and the cell responds by sending a response.  The generic cell communication is defined in this document while the cell-specific communication is described in each cell messaging document.

 

2.2   Services / Messages

Each cell in the i2b2 Hive must communicate via web services using the xml messages that can be validated by the i2b2_request.xsd and i2b2_response.xsd schemas.  The actual services provided by a cell depend on its use case.  Cellspecific xml must be placed inside the <message_body> section of the i2b2 request or response.  Each cell must describe its services and message sets in the document defining messaging for that cell.

 

The generic i2b2 request is satisfied by a <request> message which contains a <message_header>, <request_header> and <message_body>.

 

The generic i2b2 response is satisfied by a <response> message which contains a <message_header>, <response_header> and <message_body>.  The response may optionally echo the <request_header> back to the client.

 

2.3   Sequence Diagrams

All i2b2 cells must satisfy the generic use case of communicating messages.  The typical scenario for a communication between any client and any cell is illustrated, below.  The client sends a <request> message and the cell returns a <response> message.  This basic behavior is the same regardless of the outcome or status of the request.

 

 

 

2.4   XML Schema Definitions

The i2b2 XML schema consists of three XSD files:

• xsd

This schema is not used directly to create i2b2 messages, but is included in the i2b2_request.xsd and the i2b2_response.xsd.  It defines the <message_header> tag.

• xsd

This schema is used for validating i2b2 request messages.  It defines the <i2b2:request> tag, which includes the <message_header> tag.

• xsd

This schema is used for validating i2b2 response messages.  It defines the <i2b2:response> tag, which includes the <message_header> tag.

3      Example Messages

3.1   Request Example Message

<?xml version="1.0" encoding="UTF-8"?>

<i2b2:request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xmlns:i2b2="http://i2b2.mgh.harvard.edu/message"     xsi:schemaLocation="http://i2b2.mgh.harvard.edu/message

                        ./i2b2_request.xsd">

<message_header>

       <i2b2_version_compatible>0.3</i2b2_version_compatible>

        <hl7_version_compatible>2.4</hl7_version_compatible>

        <sending_application>

           

<application_name>i2b2_IdentityManagementCell</application_name>

            <application_version>0.2</application_version>

        </sending_application>

        <sending_facility>

            <facility_name>PHS</facility_name>

        </sending_facility>

        <receiving_application>

           

<application_name>i2b2_DataRepositoryCell</application_name>

            <application_version>0.2</application_version>

        </receiving_application>

        <receiving_facility>

            <facility_name>PHS</facility_name>

        </receiving_facility>

        <datetime_of_message>2000-01-

31T20:59:59.222</datetime_of_message>

        <security>

            <domain>PHS</domain>

            <username>i2b2User</username>

            <password>i2b2</password>

        </security>

        <message_type>

            <message_code>Q04</message_code>

            <event_type>EQQ</event_type>

        </message_type>

        <message_control_id>

          <session_id>session id or date</session_id>

            <message_num>zsspLPVzL4wE4dZcNeFR</message_num>

            <instance_num>0</instance_num>

        </message_control_id>

        <processing_id>

            <processing_id>P</processing_id>

            <processing_mode>I</processing_mode>

        </processing_id>

       

<accept_acknowledgement_type>messageId</accept_acknowledgement_type>         <application_acknowledgement_type/>

        <country_code>US</country_code>

    </message_header> 

    <request_header>

        <result_waittime_ms>180000</result_waittime_ms>

</request_header>    

<message_body/>

</i2b2:request>

 

3.2   Response Example Message

<?xml version="1.0" encoding="UTF-8"?>

<i2b2:response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xmlns:i2b2="http://i2b2.mgh.harvard.edu/message"     xsi:schemaLocation="http://i2b2.mgh.harvard.edu/message

                        ./i2b2_response.xsd">

    <message_header>

        <i2b2_version_compatible>0.3</i2b2_version_compatible>

        <hl7_version_compatible>2.4</hl7_version_compatible>

        <sending_application>

           

<application_name>i2b2_DataRepositoryCell</application_name>

            <application_version>0.2</application_version>

        </sending_application>

        <sending_facility>

            <facility_name>PHS</facility_name>

        </sending_facility>

        <receiving_application>

<application_name>i2b2_IdentityManagementCell</application_name>

            <application_version>0.2</application_version>

        </receiving_application>

        <receiving_facility>

            <facility_name>PHS</facility_name>

        </receiving_facility>

        <datetime_of_message>2000-01-

31T23:59:59.222</datetime_of_message>

        <security>

            <domain>PHS</domain>

            <username>i2b2User</username>

            <password>i2b2</password>

        </security>

        <message_type>

            <message_code>Q04</message_code>

            <event_type>EQQ</event_type>

        </message_type>

        <message_control_id>

            <message_num>zsspLPVzL4wE4dZcNeFR</message_num>

            <instance_num>1</instance_num>

        </message_control_id>

        <processing_id>

            <processing_id>P</processing_id>

            <processing_mode>I</processing_mode>

        </processing_id>

       

<accept_acknowledgement_type>messageId</accept_acknowledgement_type>

        <application_acknowledgement_type/>

        <country_code>US</country_code>

    </message_header>

    <response_header>         <info 

url="http://phsi2b2appdev:8080/QueryProcessor/getStatus">

                Some information here</info> 

        <result_status>

            <status type="DONE">1164738169521</status>

            <polling_url interval_ms="100"> http://phsi2b2appdev:8080/QueryProcessor/polling

</polling_url>

            <conditions>

                <condition type="WARNING" coding_system="i2b2">

                    Message here</condition>

                <condition type="ERROR" coding_system="i2b2">

                    Message here</condition>

                <condition type="FATAL_ERROR" coding_system="i2b2">

                    Message here</condition>

                <condition type="INFO" coding_system="i2b2">

                    Message here</condition>

            </conditions>

        </result_status>

    </response_header>

    <message_body/>

</i2b2:response>

4      Message Explanations 

This section describes, in more detail, elements and attributes in the i2b2 request and response header.

4.1   Request Description

When an i2b2 cell sends a XML request message, the i2b2 request message header must be included in the message along with the cell-specific message body. An example request message is shown bellow with empty cell-specific <message_body/> tag. 

In general, the request header specifies the necessary information for the receiving cell to process the request. Also, inside the <request_header/> tag, the cell can define the maximum waiting time for a request. The receiving cell is guaranteed to send back a response after that waiting time is expired regardless of the the process status of the request.

4.2   Response Description

Similar to the request messages, the i2b2 cells construct response XML messages by combing the i2b2 common response header and the cell-specific message body. As shown in the example response XML message bellow, the response header provides all the necessary data for the original requesting cell to process the response message. 

Moreover, the <response_header> tag allows the responding cell to indicate the process status of a request in the response message. For example, if there’s an error occurred, it can send back a message back in the result status type inside the <response_header>.

4.2.1     Status Type “DONE”

In a <response_header> the status should be set to “DONE” only when the request has finished successfully and all results have been returned via previous responses and the current response.

    <result_status>

        <status type="DONE">Successfully completed.</status>

        <polling_url interval_ms="50"/>

        <conditions/>

    </result_status>

4.2.2     Status Type “PENDING”

The cell wrapper may set the status type to "PENDING" and set the polling_url to something that the client may use to poll for results.  The cell wrapper does not have to send a pending message back to the client until the initial waiting period has expired.  It will continue to send a pending message back on subsequent polls until the status is set to "DONE" or "ERROR".

    <result_status>

        <status type="PENDING">Processing your request.</status>

        <polling_url

interval_ms="50">http://i2b2/polling</polling_url>

        <conditions/>

    </result_status>

4.2.3     Status Type “ERROR”

If the cell wrapper encounters some error verifying, authenticating, or validating a message, then the cell wrapper will set the status type attribute to "ERROR" and should include a text message inside the status tag with a more detailed error message.

    <result_status>

        <status type="ERROR">Your request was not formatted correctly.</status>

        <polling_url interval_ms="50"/>

        <conditions>

            <condition type="ERROR" coding_system="i2b2">Missing...</condition>

        </conditions>

    </result_status>

References

1. Dec 2006 Original document https://www.i2b2.org/software/files/PDF/current/MessageWrapper.pdf