...

i2b2 Cell Messaging

Image Removed

...

...

This document gives an overview of i2b2 cell messaging as well as a more detailed description of message formats specific to the Data Repository (CRC) Cell.

...

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/^{Image Removed}). 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.

...

Introduction
The i2b2 Hive
i2b2 Messaging Overview
XSD Files for i2b2 XML Schema
i2b2.xsd
i2b2_request.xsd
i2b2_response.xsd
i2b2 Messaging Detail
Use Cases
Services / Messages
Sequence Diagrams
XML Schema Definitions
i2b2.xsd
i2b2_request.xsd
i2b2_response.xsd
Example Messages
Request Example Message
Response Example Message
Message Explanations
Request Description
Response Description
Status Type "DONE"
Status Type "PENDING"
Status Type "ERROR"

Anchor
_Toc267560939 _Toc267560939

Anchor
_Toc148539233 _Toc148539233

Anchor
_Toc152400014 _Toc152400014

Anchor
_Toc249871773 _Toc249871773

Anchor
_Toc254702837 _Toc254702837

Anchor
_Toc148539234 _Toc148539234

Introduction

This document gives an overview of i2b2 cell messaging as well as a more detailed description of message formats specific to the Data Repository (CRC) Cell.

Anchor
_Toc249871774 _Toc249871774

Anchor
_Toc254702838 _Toc254702838

Anchor
_Toc148539235 _Toc148539235

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.

Anchor
_Toc249871775 _Toc249871775

Anchor
_Toc254702839 _Toc254702839

Anchor
_Toc148539236 _Toc148539236

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 image illustrates the basic top-level elements contained within the request and response messages.

Image Added

Anchor
_Toc148539237 _Toc148539237

XSD Files for i2b2 XML Schema

The i2b2 XML schema consists of three XSD files:

Anchor
_Toc254702840 _Toc254702840

Anchor
_Toc148539238 _Toc148539238

i2b2.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.

Anchor
_Toc254702841 _Toc254702841

Anchor
_Toc148539239 _Toc148539239

i2b2_request.xsd

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

Anchor
_Toc254702842 _Toc254702842

Anchor
_Toc148539240 _Toc148539240

i2b2_response.xsd

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

Anchor
_Toc148539241 _Toc148539241

i2b2 Messaging Detail

Anchor
_Toc148539242 _Toc148539242

Use Cases

All i2b2 cells must satisfy one specific use case which is to communicate. The specific 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 which the cell-specific communication is described in each cell messaging document.

Image Added

Anchor
_Toc148539243 _Toc148539243

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. Cell-specific 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.

Anchor
_Toc148539244 _Toc148539244

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.

Image Added

Anchor
_Toc148539245 _Toc148539245

XML Schema Definitions

The i2b2 XML schema consists of three XSD files:

Anchor
_Toc148539246 _Toc148539246

i2b2.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.

Anchor
_Toc148539247 _Toc148539247

i2b2_request.xsd

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

Anchor
_Toc148539248 _Toc148539248

i2b2_response.xsd

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

Anchor
_Toc148539249 _Toc148539249

Example Messages

Anchor
_Toc148539250 _Toc148539250

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>demo</username>
               <password>demouser</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>

Anchor
_Toc148539251 _Toc148539251

Response

...

The i2b2 XML schema consists of three XSD files:

...

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.

...

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

...

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

...

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. Cell-specific 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.

...

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.

...

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

...

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>demo</username>
               <password>demouser</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>

...

...

<?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>demo</username>
               <password>demouser</password>
          </security>
          <message_type>
               <message_code>Q04</message_code>
_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+^{Image Removed} </polling_url>
<conditions>
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>

...

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".
<results_status>
<status type="PENDING">Processing your request.</status>
<polling_url interval_ms="50">http://i2b2/polling^{Image Removed}</polling_url>
<conditions/>
</result_status>

...