...
// 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 = {}; |
...
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.
i2b2.ONT.cfg.msgs.GetSchemes =
'<?xml version="1.0" encouding="UTF-8" standalone="yes"?>\n'
'<ns3:request xmlns:ns3="http://www.i2b2.org/xsd/hive/mghs/1.1."
xmlns:ns4="http://www.i2b2.org/xsd/cell/ont/1.1/"
xmlns:ns2="http://www.i2b2.org/xsd/hive/plugin/">\n'
' <message_header>\n'
' {proxy_info}\n'
' <i2b2_version_compatible>1.1</i2b2_version_compatible>\n'
' <hl7_version_compatible>2.4</hl7_version_compatible>\n'
' <receiving_facility>\n'
' <facility_name>i2b2 Hive</facility_name>\n'
' </receiving_facility>\n'
' <datetime_of_message>{header_msg_datetime}</datetime_of_message>\n'
' <security>\n'
' <domain>{sec_domain}</domain>\n'
' <username>{sec_user}</username>\n'
' {sec_pass_node}\n'
' </security>\n'
' <message_control_id>\n'
' <message_num>{header_msg_id}</message_num>\n'
' <instance_num>0</instance_num>\n'
' </message_control_id>\n'
' <processing_id>\n'
' <processing_id>P</processing_id>\n'
' <processing_mode>I</processing_mode>\n'
' </processing_id>\n'
' <accept_acknowledgement_type>AL</accept_acknowledgement_type>\n'
' <application_acknowledgement_type>AL</application_acknowledgement_type>\n'
' <country_code>US</country_code>\n'
' <project_id>{sec_project}</project_id>\n'
' </message_header>\n'
' <request_header>\n'
' <result_waittime_ms>{result_wait_time}000</result_waittime_ms>\n'
' </request_header>\n'
' <message_body>\n'
' <ns4:get_schemes type="default"/>\n'
' </message_body>\n'
'</ns3:request>'; |
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.
...
i2b2.ONT.cfg.parsers.GetSchemes = function(){
if (!this.error){
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0da2e64b-edee-4a2e-a1aa-574cfffe1b6f"><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="e1e349be-d6ff-4bc0-b67c-80faaa4ce83e"><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="cddda744-7eec-4d74-8fb6-2097305a8300"><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="a2d0d5a3-f376-4b58-8b36-c4bfe274b0bc"><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="c6f485bb-0011-497f-9c58-8ee55b7baa2e"><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="e776855c-b000-47ea-ad55-17f825ebdcbf"><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 |
|---|
|
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 |
...
i2b2.ONT.ajax._addFunctionCall("GetSchemes",
"{URL}getSchemes",
i2b2.ONT.cfg.msgs.GetSchemes,
null,
i2b2.ONT.cfg.parsers.GetSchemes); |
The required first parameter of the _addFunctionCall() determines the name of the communicator function that will be added to the base communicator object. In this example, the communicator method i2b2.ONT.ajax.GetSchemes() is created.
The required second parameter is a string used to define the URL used to access the webservice on the i2b2 hive back-end. The special {URL} tag is replaced with the base URL of the Cell's hive webservice retrieved during the login process. The highlighted line below shows where this URL value is found in the results of the getUserAuth message from the PM Cell.
The required third parameter is a reference to the XML message template that is to be sent to the i2b2 hive back-end when the i2b2.ONT.ajax.GetSchemes() communicator method is called. The message always has its special tags replaced with the values passed to the communicator method.
The optional fourth parameter is an array containing the names of tags used in the XML message template that should NOT be escaped. For example, if a specific message tag is supposed to be interpreted as additional XML elements you will want to make sure that it is not escaped automatically by the communicator subsystem. If you are not using this parameter you can omit it from the function parameter list unless you are passing a 5th parameter, in which case you should set the 4th parameter to be null. An example of passing values using the optional 4th parameter is as follows:
i2b2.CRC.ajax._addFunctionCall("runQueryInstance_fromQueryDefinition",
"{URL}request",
i2b2.CRC.cfg.msgs.runQueryInstance_fromQueryDefinition,
| Wiki Markup |
|---|
*\[*"psm_result_output"| Wiki Markup |
|---|
*, \ [*"psm_query_definition"| Wiki Markup |
|---|
*, \ [*"shrine_topic"]); |
The optional fifth parameter is a reference to a special parser function that is used to extract information from the XML message returned from the i2b2 Hive back-end. If you are not using a parser then you can omit it from the function parameter list. The parser function that is passed to create a communication method via the _addFunctionCall function is said to be the "default message parser".
...
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 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",
};
// define a simple function to allow asynchronous call to the i2b2 Hive back-end
var simpAsyncCallback = function (results_cdo) {
// 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);
{color:#333333}};
// use asynchronous call to request results from the i2b2 Hive back-end
i2b2.ONT.ajax.GetNameInfo ("originated by test", tagValues, simpAsyncCallback); |
Here is a code example that executes a callback function asynchronously within the scope of Firebug's console object:
// 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",
};
// define a simple function to allow asynchronous call to the i2b2 Hive back-end
var complexAsyncCallback = function (results_cdo) {
// dump the Communication Data Object variable (Firefox w/Firebug only)
this.dir (results_cdo);
// dump the sent xml (Firefox w/Firebug only)
this.debug (results_cdo.msgRequest);
// dump the returned xml (Firefox w/Firebug only)
this.debug (results_cdo.msgResponse);
};
// create scoped-callback object (attaches execution scope to complexAsynchCallback)
var scopedCB = new i2b2_scopedCallback (complexAsyncCallback, window.console) ;
// use asynchronous call to request results from the i2b2 Hive back-end
i2b2.ONT.ajax.GetNameInfo ("originated by test", tagValues, simpAsyncCallback); |
Alternatively, you can define a scoped callback object in the following way, which may make your code more readable:
// 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")
...
The following code shows how to use the default parser function on a returned Communication Data Object:
// executing from Firebug console window, run synchronous GetSchemes webservice
// call with a debug title of "testing" and empty template vars denoted with {}
var testing = i2b2.ONT.ajax.GetSchemes ("test msg", {}) ;
console.dir (testing) ;
// run the default GetSchemes parser and populate the "model" attribute of the CDO
testing.parse () ;
// dump the first record from the "model" attribute of the CDO
console.dir (testing.model[0]) ; |
The results will be output as so:
...
