IM-JS

Class: IMJS

api. IMJS

IMJS is the entry point for the IMJS framework.

IMJS can be used to retrieve structures and data from the SDMX Web Services

To obtain an instance of IMJS call the static api.IMJS.getInstance method passing in the configuration.

new IMJS()

Examples

Showing how to create an Instance and how to obtain the instance one a connection has been established

function createConnection(serverUrl)
    config = {
    	url: serverUrl,
     includeMetadata: true,
     loadingListener: loading
    }
    
    //The first call takes a configuration which establishes a connection to the URL defined in the configuration
    IMJS.getInstance(config);
  }
  
  function doSomething {
    //To obtain an instance once the connection has been established, simply call the static getInstance() method
    var instance = IMJS.getInstance();
  }

Display All Dataflows in a HTML Table

function displayDataflows() {
  IMJS.getInstance().getDataflows(null, null, null, true, onDataflowResponse);
}

function onDataflowResponse(flows) {
   var html = "<table>";
   
   //Create the Table Head (static)
   html += "<thead>";
   html += "<th>Agency Id</th>";
   html += "<th>Id</th>";
   html += "<th>Version</th>";
   html += "<th>Name</th>";
   html += "<th>Series Count</th>";
   html += "</thead>";
      
   //Create the Table Body (dynamic)
   html += "<tbody>";
   for(var i=0; i < flows.length; i++) {
     var currentFlow = flows[i];
     var seriesCount = currentFlow.hasMetrics() ? currentFlow.getMetrics().getSeriesCount() : 0;
     
     html += "<td>"+currentFlow.getAgencyId()+"</td>";
     html += "<td>"+currentFlow.getId()+"</td>";
     html += "<td>"+currentFlow.getVersion()+"</td>";
     html += "<td>"+currentFlow.getName()+"</td>";
     html += "<td>"+seriesCount+"</td>";
   }
   html += "</tbody>";
   html += "</table>";
    
   //do something with HTML - this example uses JQuery to append to an existing Div by Id
   $("#divElement").html(html)
}

Construct and execute a Data Query and render a HTML Pivot table

function createDataQuery(dataflowUrn) {
  //Obtain the Dataflow which the Data Query will be built for
  IMJS.getInstance().getIdentifiable(dataflowUrn, onDataflowResponse);
}

function onDataflowResponse(dataflow) {
  //Create a Data Query - do not store the state of the Query on the URL
	 dataflow.createDataQuery(false, onCreateQueryResponse);
}

function onCreateQueryResponse(dataQuery) {
  //Add query filters and execute the query on the server
  dataQuery.addCodeSelection("FREQ", "A");
  dataQuery.addCodeSelection("REF_AREA", "UK");
  dataQuery.executeQuery(null, onDataQueryResponse); 
}

function onDataQueryResponse(dataset) {
  //Render the response as a HTML Pivot Table
	 var pivotTable = new PivotTable("#tableDiv");
	 pivotTable.draw(dataset)
}

Methods

<static> getInstance(config)

Returns an instance of IMJS on first call a configuration is required, on subsequent calls the configuration is not required
and will be ignored if provided

Parameters:
Name Type Description
config object

Configuration options are a JSON Object with the following key value pairs, the only required parameter is the URL.
Returns:

an instance of IMJS

Type
api.IMJS
Example

Showing how to create an Instance and how to obtain the instance one a connection has been established

function createConnection(serverUrl)
    config = {
    	url: serverUrl,
     includeMetadata: true,
     loadingListener: loading
    }
    IMJS.getInstance(config);
  }

callDataService(queryUrl, callback)

Get a data.DataSet from the Given URL.

Parameters:
Name Type Description
queryUrl string

URL postfix starting with "data/{query}" where {query} is the query you would like to execute.
callback api.IMJS~callDataService

a given function to call when the query has complete. The function must take one parameter which is the response
See:
Example
IMJS.getInstance().callDataService("data/WB,EDUCATION,1.0/A..ARN?format=sdmx-json", function(jsonResponse) {
	console.log(jsonResponse)
);

getAgency(agencyId, id, callback)

Returns a Agency with the given Id, maintained by the given agencyId, to the callback function.

Parameters:
Name Type Description
agencyId string

the agencyId that owns this Agency, if not supplied this will default to the Agency 'SDMX' who owns all the top level Agencies
id string

the id of the Agency to be returned
callback function

A callback function expected to take one argument, the AgencyBean
Example
IMJS.getInstance().getAgency(null, "IMF", function(acy) {
    if(!acy) {
      console.log("No Agency Found")
    } else {
      console.log(acy.getUrn());  //Acy is the returned Agency
	   }
});

getAgencyByFullId(fullId, callback)

Returns a Agency with the given full Id, for sub-agencies the full id includes the owning agencies, for example:

fullId = ORG1.DEPT1.SUBDEPT where
agencyId = SUBDEPT
owning agency fullid = ORG1.DEPT1

The callback function is called with teh AgencyBean

Parameters:
Name Type Description
fullId string

the full id of the Agency to be returned
callback function

A callback function A callback function expected to take one argument, the AgencyBean
Example
IMJS.getInstance().getAgencyByFullId("IMF.SUBACY",function(acy) {
    if(!acy) {
      console.log("No Agency Found")
    } else {
      console.log(acy.getUrn());  //Acy is the returned Agency
	   }
});

getAgencySchemes( [agencyId], callback)

Returns an array of AgencySchemes that match the agency and id to the callback function - these are all optional filters.

Parameters:
Name Type Argument Description
agencyId string <optional>

If supplied, all returned AgencySchemes will be owned by this Agency
callback function

A callback function expected to take one argument, an array of AgencySchemes or an empty array if none match the query criteria
Example
IMJS.getInstance().getAgencySchemes(null,  function(acySch) {
	for(var i=0; i < acySch.length; i++) {
    var currentScheme = acySch[i];
     console.log(currentScheme.getUrn());  
 }
});

getCategorySchemes( [agencyId] [, id] [, version], callback)

Returns an array of CategorySchemes that match the agency, id, and version to the callback function - these are all optional filters.

Parameters:
Name Type Argument Description
agencyId string <optional>

If supplied, all returned Category Schemes will be owned by this Agency
id string <optional>

If supplied, all returned Category Schemes will have this Id
version string <optional>

If supplied, all returned Category Schemes will be this version
callback function

A callback function expected to take one argument, an array of CategorySchemes or an empty array if none match the query criteria
Example
IMJS.getInstance().getCategorySchemes("ECB", "DEMO_CATEGORIES", "1.0", function(catSch) {
	for(var i=0; i < acycatSch.length; i++) {
    var currentScheme = catSch[i];
    console.log(currentScheme.getUrn());  
 }
});

getCodelists( [agencyId] [, Id] [, Version], callback)

Returns an array of Codelists that match the agency, id, and version to the callback function - these are all optional filters.

Parameters:
Name Type Argument Description
agencyId string <optional>

If supplied, all returned Codelist will be owned by this Agency
Id string <optional>

If supplied, all returned Codelist will have this Id
Version string <optional>

If supplied, all returned Codelist will be this version
callback function

A callback function expected to take one argument, an array of Codelists or an empty array if none match the query criteria
Example
IMJS.getInstance().getCodelists("ECB", null, "1.0", function(v1Codelists) {
	for(var i=0; i < v1Codelists.length; i++) {
    var currentCodelist= v1Codelists[i];
    console.log(currentCodelist.getUrn());  
 }
});

getConfigValue(value)

Get a value from the config

Parameters:
Name Type Description
value string

The key name
Returns:

The value

Type
string

getCrossReferencing(the, if, callback [, async])

Gets the MaintainableBeans which cross reference this structure

The MaintainableBeans that match the query parameters are returned to
the callback function in a BeansContainer

Parameters:
Name Type Argument Description
the bean.base.MaintainableBean

maintainable to get cross references for
if string

provided will filter the response to only return structures that cross reference which are of the given type
callback IMJS~maintCallBack

A callback function A callback function expected to take one argument, the BeansContainer
async boolean <optional>

if false, this method will not be async
Throws:

If callback and structureQuery are not defined

Type
TypeError

getDataflow(agencyId, id, version [, includeMetrics], callback)

Returns a Dataflow that matches the agency, id, and version.

If there are no Dataflow matches, the callback will be called with a null argument.

If more then one Dataflow matches the query, then the first Dataflow in the response will be returned

Parameters:
Name Type Argument Description
agencyId string

The returned Dataflow will be owned by this Agency
id string

The returned Dataflow will have this Id
version string

The returned Dataflow will be this version
includeMetrics string <optional>

If true then the returned Dataflows will include Metrics @see bean.datastructure.DataflowBean#getMetrics
callback IMJS~maintCallBack

A callback function A callback function expected to take one argument, the BeansContainer
Example
IMJS.getInstance().getDataflow("ECB", "DF_EXR", "1.0", true, function(exrDf) {
	   if(!exrDf) {
 	 console.log("Not Found")
    } else {
      console.log(exrDf.getUrn());  
    }
});

getDataflows( [agencyId] [, id] [, version] [, includeMetrics], callback)

Returns an array of Dataflows that match the agency and id to the callback function - these are all optional filters.

Parameters:
Name Type Argument Description
agencyId string <optional>

If supplied, all returned Dataflow will be owned by this Agency
id string <optional>

If supplied, all returned Dataflow will have this Id
version string <optional>

If supplied, all returned Dataflow will be this version
includeMetrics string <optional>

If true then the returned Dataflows will include Metrics @see bean.datastructure.DataflowBean#getMetrics
callback function

A callback function expected to take one argument, an array of Dataflows or an empty array if none match the query criteria
Example
IMJS.getInstance().getDataflows("ECB", null, "1.0", true, function(v1Dataflows) {
	for(var i=0; i < v1Dataflows.length; i++) {
    var currentDataflow = v1Dataflows[i];
    console.log(currentDataflow.getUrn());  
 }
});

getIdentifiable(urn, callback [, returnStub] [, useCache] [, async] [, includeMetrics])

Get the IdentifiableBean that from matches the URN.

Parameters:
Name Type Argument Default Description
urn string

The urn of the IdentifiableBean to return
callback IMJS~maintCallBack

A callback function expected to take one argument, the IdentifiableBean
returnStub boolean <optional>
 false

If true then the stub will be returned
useCache boolean <optional>
 true

if true, this method will first check the client side cache for the requested structure
async boolean <optional>
 true

if false this method will not be performed asynchronously
includeMetrics boolean <optional>
 false

if true, this will supply metrics about the structure (how many series, data from and date to). This argument is only relevant for Provision Agreements and Dataflows
Throws:

If the callback is not a function

Type
TypeError

getMaintainables(structureQuery, callback [, async] [, includeMetrics])

Gets the MaintainableBeans from the Registry that match the given StructureQuery

The MaintainableBeans that match the query parameters are returned to the callback function in a BeansContainer

Parameters:
Name Type Argument Default Description
structureQuery bean.StructureQuery

The query object to execute on
callback IMJS~maintCallBack

A callback function A callback function expected to take one argument, the BeansContainer
async boolean <optional>
 false

if false, this method will not be async
includeMetrics boolean <optional>
 false

if true, this will supply metrics about the structure (how many series, data from and date to). This argument is only relevant for Provision Agreements and Dataflows
Throws:

If callback and structureQuery are not defined

Type
TypeError

getServerUrl()

Returns the server URL that was used in establishing a connection

Returns:

The server URL

Type
string

getSupportedLanguages()

Returns an array of languages that the Fusion Registry has metadata for

Returns:

array of lang

Type
Array.<string>

getURLHashValue(param)

Returns the parameter value in the hash '#' part of the URL. This part of the URL is used to record state.

Parameters:
Name Type Description
param

the parameter to return the value for
Returns:
Type
string
Example
URL: http://[youruser]/data.html#tp=mytopic;pv=123

var tp = IMJS.getInstance().getURLHashValue("tp");
console.log(tp) //this should log mytopic

setConfig(config, value)

Set or override a config value
Only locale or includeMetadata may be changed

Parameters:
Name Type Description
config string

the config you want to set or change
value string

the value you want to set it to
Throws:

If the config is not includeMetadata or locale

Type
TypeError

setURLHashParam(param, value)

Updates the parameter value with the given value

Parameters:
Name Type Description
param string

the parameter
value string

the value
Example
IMJS.getInstance().setURLHashParam("tp", "mytopic");

this will update the URL to contain this key value after the hash on the URL, for example:
http://[youruser]/data.html#tp=mytopic

Type Definitions

getDataSetFromUrlCallBack(dataSet)

The callback from getDataSetFromUrl

This:
Parameters:
Name Type Description
dataSet data.DataSet

The data from your query

maintCallBack(container)

The callback from getMaintainable

This:
Parameters:
Name Type Description
container bean.BeansContainer

of all the constructed objects from the registry