i2b2 Web Client
Space shortcuts
Space Tools

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

2a

A communications method call is made to the i2b2.CELLCODE.ajax.METHODNAME.

2b

The generic communicator code performs a synchronous or asynchronous call to the i2b2 hive back-end and retrieves the results.

2c

The cell communicator returns a standardized Communications Message Object containing the resultant XML as well as an optional method called parse ().

2d

Calling the parse () method of the Communications Message Object will cause a JavaScript array called data to be added to the object which contains information extracted by the default associated parser routine. If an error is encountered data === false.



Creating a Communicator Object

Object Instantiation and Definition of Data Namespaces

Create an instance of the generic communicator object using a call to i2b2.hive.communicatorFactory() function and save it to the ajax namespace of your cell or plug-in. You will also need to define a namespace to hold the XML message templates used to send requests to the i2b2 Hive.

...

// create the communicator Objecti2b2.ONT.ajax = i2b2.hive.communicatorFactory ("ONT");

// create namespaces to store the communicator's msg templates and parsers
i2b2.ONT.cfg.msgs = {};
i2b2.ONT.cfg.parsers = {};



Definition of XML Message

Now the individual XML message templates need to be created. These templates are simply strings saved into the msgs namespace. Best practice is to save them using a name that is the same as the i2b2 Hive RPC call.

...



Placeholder tags starting, and ending, with three curly brackets ( "{" and "}" ) are contained throughout this message string. Between the tag's curly brackets is its non-space containing name used to identify the tag. These tags are replaced with values passed in the call parameters when the communication method is invoked.

Reserved Tag Names

There are a number of reserved tag names that are automatically defined by the i2b2 web client framework. You may (and most like will) use these tags in your message.

...

Tag Name

Example Value

Description

{proxy_info}

<proxy>
<redirect_url>
http://services.i2b2.org/i2b2/rest/PMService/getServices
</redirect_url>

Information used by the Web Client's proxy server

{sec_domain}

HarvardDemo

Domain of current project

{sec_project}

Demo

Code of current project

{sec_user}

demo

User currently logged in

{sec_pass_node}

<password token_ms_timeout='1800000' is_token='true'>
SessionKey:ewIalmaQCnWuhAh5mooW
</password>

See Documentation on Hive Project Management Cell

{header_msg_id}

mQgJaD4z12dd2vLWWzY64

Runtime generated GUID

{header_msg_datetime}

2010-05-19T13:24:35-04:00

Current datetime in ISO8601

{result_wait_time}

180

Max query time in seconds



Message Parser Creation

You may create a message parser to simplify your own code and to allow other developers to more easily integrate with your standardized cell communicator. When your parser is invoked its this variable references the standard Communicator Results Object ("CRO") that is returned by the communicator subsystem.

i2b2.ONT.cfg.parsers.GetSchemes = function(){
     if (!this.error){
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="10a3cf13307cfa24-7894014a-439f4055-b2e9a791-c614cb0b1471357945823251"><ac:plain-text-body><![CDATA[           this.model = [];
           // extract records from XML msg
]]></ac:plain-text-body></ac:structured-macro>
           var c = this.refXML.getElementsByTagName('concept');
           for (var i=0; i < 1 * c.length; i++) {
                var o = new Object;
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b50f39066fa5d306-3d367528-49a448b5-bd3f9592-73142b5fcbe12213ffe537b2"><ac:plain-text-body><![CDATA[                o.xmlOrig = c[i];
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c7fdd5e195fca816-f500065f-45ec429e-be72a4ce-8d7580819dd64832c0c406fb"><ac:plain-text-body><![CDATA[                o.level = i2b2.h.getXNodeVal(c[i],'level');
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="e9eefdfc98281a61-17de687b-46174903-a4ce88ae-3e0877b7e0677da567d2569a"><ac:plain-text-body><![CDATA[                o.key = i2b2.h.getXNodeVal(c[i],'key');
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="997b8d490f0396d9-6cf621d5-49f54599-92bb8e4d-84e27e3f695286280e41c56f"><ac:plain-text-body><![CDATA[                o.name = i2b2.h.getXNodeVal(c[i],'name');
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="19c64e3c195209f6-0aace7ad-44f64c21-807a82a7-2d7fd5341c83b6275044daa4"><ac:plain-text-body><![CDATA[                o.total_num = i2b2.h.getXNodeVal(c[i],    &'totalnum');
]]></ac:plain-text-body></ac:structured-macro>
                 // save extracted info
                  this.model.push(o);
           }
      } else {
            this.model = false;
            console.error(

Wiki Markup
"\[GetSchemes\] Could not parse() data\!"
);
      }
     return this;
}; |

...

Note
titleBe Careful

Very specific behavior is expected from your parser function! Your parser is expected to create an array called this.model containing a list of values or JavaScript objects representing data from the XML message. If an error occurs, your parser is expected to set this.model = false. Your parser routine must always return the reference to its this variable



Creating Communication Methods

The generic communicator object returned by calling the i2b2.hive.communicatorFactory() function consist of several private use functions and data structures. The _addFunctionCall() function is to be used by your initialization routine to create communicator methods that are to be called by non-framework code, such as the code in your cell / plug-in. To continue with this section's example and create the ONT cell's GetSchemes communication method the following code is executed:

...

Note
titleBe Careful

To ensure stability of your Web Client deployment, do not change the default message parser of any cell or plug-in this is not owned in-house.
If a cell / plug-in does not extract all the information you need from its XML message you can copy the code to your own namespace, modify it, and pass its references as a parameter to the Communication Data Objects parse() function. Doing this will override usage of the default message parser in a way that will allow code updates without stability issues related to version mismatches or applying custom patches.



Using the Communicator

Standard Communication Method Parameters

All communication methods created using the _addFunctionCall() function of a communicator instance operate in exactly the same way and consume the same parameters. Below is a list of all parameters of a standard communications method:

Parameter

Required

Description

originName

N

String that is used to identify and group all messages using the message sniffer subsystem.

tagValues

N

A JavaScript object using tagname / value pairs. An example would be:
{ ont_synonym_records: "N",
ont_hidden_records: "N",
ont_search_strategy: "contains",
ont_search_string: "asthma" }

scopedCallback

Y

A scopedCallback object or regular function used to enable asynchronous AJAX calls.
If omitted, synchronous calls are used instead.

transportOptions

Y

Transport options passed directly to Prototype's AJAX object.
See http://api.prototypejs.org/ajax/ajax/request/ for more information.



Synchronous Call Example

A code example showing how to perform a synchronous request on a standard communicator method:

// create the object containing tag/value pairs to be used by the XML msg template
var tagValues = { ont_synonym_records" "N",
                           ont_hidden_records" "N",
                           ont_search_strategory" "contains",
                           ont_search_string" "asthma",
                        };
// use synchronous call to request results from the i2b2 Hive back-end
var results_cdo = i2b2.ONT.ajax.GetNameInfo ("originated by test", tagValues);

// dump the Communication Data Object variable (Firefox w/Firebug only)
console.dir (results_cdo);

// dump the sent xml (Firefox w/Firebug only)
console.debug (results_cdo.msgRequest);

// dump the returned xml (Firefox w/Firebug only)
console.debug (results_cdo.msgResponse);



Asynchronous Call Example

Here is a code example showing how to perform an asynchronous request on a standard communicator method:

...

// create scoped-callback object (attaches execution scope to complexAsynchCallback)
var scopedCB = new i2b2_scopedCallback () ;
scopedCB.scope = window.console;
scopedCB.callback =complexAsyncCallback;



Communication Data Object ("CDO")

All standardized communication method calls, regardless of synchronous or asynchronous execution, return a standard results object known as a Communication Data Object which contains details of the messages passed back and forth between the web client and the i2b2 Hive back-end.

Attribute Name

Type

Description

Result.error

Boolean

Information used by to Web Client's proxy server

Result.msgRequest

String

The message that was sent to the proxy server (and thus the i2b2 Hive web service)

Result.msgResponse

String

Code of current project

Result.msgUrl

String

The URL used to access the i2b2 Hive web service call.

Result.msgUrlProxy

String

The URL of the proxy that the web client sent the message to.

Result.refXML

XMLDOM

A reference to a XMLDOM object containing the response message.

Result.parse()

Function

A function called by a developer's code to automatically parse the XMLDOM and save the results in Result.model attribute.

Result.model

Null or Array

This attribute is created after calling the parse() function.



Message Parser Examples

The following code shows how to use the default parser function on a returned Communication Data Object:

...