Parse Data Returned by Intelligence Server

The code that renders a custom HTML5 visualization must parse the MicroStrategy data returned by the Intelligence Server. The Data Interface API provides methods to help you navigate through the data on a JavaScript layer so that you can provide it to your visualization.

You can use the DataInterface class to help you parse data for consumption by the visualization. In addition to methods to navigate through data on a JavaScript layer, this class includes one method that automatically returns data in the format expected by most D3 visualizations, eliminating the need for you to parse the data at all.

MicroStrategy data is returned by the Intelligence Server in the grid format shown below. The sample data in this grid is used in the explanation of the methods in the Data Interface API.

The titles in the grid (ROW TITLE and COLUMN HEADER) are objects that come from the metadata. The headers and metric values (ROW HEADER and METRIC VALUE) are values that come from the data warehouse. COLUMN TITLE is a hidden column in a dashboard; in a document, it is the Metrics column that MicroStrategy inserts by default. In both, it is accessible using the methods in the Data Interface API. 

The Data Interface API contains the classes shown below. An explanation of the relevant methods in each class are provided. The explanation includes an example of what the method returns, based on the sample grid shown above.

• mstrmojo.models.templates.DataInterface
• mstrmojo.models.templates.Titles
• mstrmojo.models.templates.Title
• mstrmojo.models.templates.Headers
• mstrmojo.models.templates.Header
• mstrmojo.models.templates.MetricValue

When a method expects a position as an input, the position is expressed as a single index value, where the index value begins with "0", for ROW TITLES, COLUMN TITLES, COLUMN HEADERS, ROW HEADERS. In the case of a METRIC VALUE, the position is expressed in the format column index, row index. The index values shown in the examples below reflect those in the sample grid shown above.

mstrmojo.models.templates.DataInterface

To get the DataInterface object, use code similar to the following:

var di = this.dataInterface;

where this is a context of the current visualization, which extends CustomVisBase.

DataInterface uses the following methods to parse data for use in a custom HTML5 visualization. In the code samples below, gridData is used as a pointer to an instance of DataInterface.

• getTotalRows()
  Returns the number of rows in the grid.
  Returns: Integer
  For example, using the grid above, this method would return "12".

• getTotalCols()
  Returns the number of metric columns in the grid.
  Returns: Integer
  For example, using the grid above, this method would return "2".

• getColumnHeaderCount()
  Returns the number of metric column headers in the grid.
  Returns: Integer
  For example, using the grid above, this method would return "2".

• getRawData(format, params)
  Returns the data in the format specified by the enumeration value for the format and the parameters.
  Returns: Array/tree data

  Parameters:

  • format

  The enumeration value that specifies the format in which the JSON should be returned. For example, ENUM_RAW_DATA_FORMAT.TREE returns JSON in a tree format. ENUM_RAW_DATA_FORMAT.ROWS_ADV returns JSON in an array format.

  • params

    The parameters are optional and differ for each format. The parameters for the tree format include the following options:

    • descKey

      Key's name for object description. Default value is "name".

    • childrenKey

      Key's name for child collection. Default value is "children". It can be changed to "nodes" for D3 data.

    • hasSelection

      Boolean flag that indicates whether to include encapsulated information for the object selection. AttributeSelector and MetricSelector will be included in each object and leaf. Default value is false. This parameter is required when you use a visualization as a selector.

    • hasThreshold

      Boolean flag that indicates whether to include threshold information. The threshold information comes with each metric value and contains the color code where the value falls in the threshold definition. Default value is false.

    • hasTitleName

      Boolean flag that indicates whether to include the title name of the object. Default value is false.

    • needDecode

      Boolean flag that indicates whether to decode the HTML tags int he element name and title name. It may affect performance when used for big data. Default value is false.

    • nestedLevel

      Maximum level the tree will be nested. If there are five attributes in a row and the nested level is two, only the first attributes will be counted int he tree, and te remaining three will be ignored. Default value is undefined.

    The parameters for the array format include the following options:

    • hasSelection

      Boolean flag that indicates whether to include encapsulated information for the object selection. AttributeSelector and MetricSelector will be included in each object and leaf. Default value is false. This parameter is required when you use a visualization as a selector.
      

    • hasThreshold

      Boolean flag that indicates whether to include threshold information. The threshold information comes with each metric value and contains the color code where the value falls in the threshold definition. Default value is false.

    • hasTitleName

      Boolean flag that indicates whether to include the title name of the object. Default value is false.

    • needDecode

      Boolean flag that indicates whether to decode the HTML tags int he element name and title name. It may affect performance when used for big data. Default value is false.

  Examples:

  Using the grid above, if you pass in mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.TREE as the format, the getRawData method would return the JSON tree format shown below and expected by some D3 visualizations.

  Copy

  [{"name":"root","children":[{"name":"Books","children":[{"name":"2010","value":650191.65,"formattedValue":"$650,192"}]},{"name":"Books","children":[{"name":"2011","value":868206 "formattedValue":"$868,207"}]},{"name":"Books","children":[{"name":"2012","value":1121696.3,"formattedValue":"$1,121,696"}]},{"name":"Electronics","children":[{"name":"2010","value":6027842.65,"formattedValue":"$6,027,843"}]},{"name":"Electronics","children":[{"name":"2011","value":8020662.15,"formattedValue":"$8,020,662"}]},{"name":"Electronics","children":[{"name":"2012","value":10342798.05,"formattedValue":"$10,342,798"}]},{"name":"Movies","children":[{"name":"2010","value":1012594.3,"formattedValue":"$1,012,594"}]},{"name":"Movies","children":[{"name":"2011","value":1345502.35,"formattedValue":"$1,345,502"}]},{"name":"Movies","children":[{"name":"2012","value":1740846.8,"formattedValue":"$1,740,847"}]},{"name":"Music","children":[{"name":"2010","value":956609.5,"formattedValue":"$956,610"}]},{"name":"Music","children":[{"name":"2011","value":1283235,"formattedValue":"$1,283,235"}]},{"name":"Music","children":[{"name":"2012","value":1653522.9,"formattedValue":"$1,653,523"}]}]

  Using the grid above, if you pass in mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.ROWS_ADV as the format, the getRawData method would return the JSON array format shown below and expected by some D3 visualizations.

  Copy

  [{"headers":[{"name":"Books"},{"name":"2010"}],"values":[{"v":"650192.00","rv":650192},{"v":"12","rv":12}]},
  {"headers":[{"name":"Books"},{"name":"2011"}],"values":[{"v":"868206.00","rv":868206},{"v":"11","rv":11}]},
  {"headers":[{"name":"Books"},{"name":"2012"}],"values":[{"v":"1121696.00","rv":1121696},{"v":"8","rv":8}]},
  {"headers":[{"name":"Electronics"},{"name":"2010"}],"values":[{"v":"6027843.00","rv":6027843},{"v":"2","rv":2}]},
  {"headers":[{"name":"Electronics"},{"name":"2011"}],"values":[{"v":"8020662.00","rv":8020662},{"v":"3","rv":3}]},
  {"headers":[{"name":"Electronics"},{"name":"2012"}],"values":[{"v":"10342798.00","rv":10342798},{"v":"1","rv":1}]},
  {"headers":[{"name":"Movies"},{"name":"2010"}],"values":[{"v":"1012594.00","rv":1012594},{"v":"9","rv":9}]},
  {"headers":[{"name":"Movies"},{"name":"2011"}],"values":[{"v":"1345502.00","rv":1345502},{"v":"6","rv":6}]},
  {"headers":[{"name":"Movies"},{"name":"2012"}],"values":[{"v":"1740847.00","rv":1740847},{"v":"4","rv":4}]},
  {"headers":[{"name":"Music"},{"name":"2010"}],"values":[{"v":"956609.00","rv":956609},{"v":"10","rv":10}]},
  {"headers":[{"name":"Music"},{"name":"2011"}],"values":[{"v":"1283235.00","rv":1283235},{"v":"7","rv":7}]},
  {"headers":[{"name":"Music"},{"name":"2012"}],"values":[{"v":"1653523.00","rv":1653523},{"v":"5","rv":5}]}]

  You can also pass parameters to request extra information as shown below:

  Copy

  getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.TREE, {
     hasTitleName: true,
     hasSelection: true,
     needDecode: true
  });

• getRowTitles()
  Returns row titles in the format mstrmojo.models.templates.Titles.  
  Returns: Array of ROW TITLE objects
  For example, using the grid above, if you used gridData.getRowTitles().getTitle(0).getName(), this method would return "Category".

• getColTitles()
  Returns column titles in the format mstrmojo.models.templates.Titles.
  Returns: array of COLUMN TITLE objects
  For example, using the grid above, if you used gridData.getColTitles().getTitle(0).getName(), this method would return "Metrics".

• getRowHeaders(pos)
  Returns attribute headers for a given row (an array ), where pos is the index of the row, in the format mstrmojo.models.templates.Headers.
  Returns: Array of ROW HEADER objects
  For example, using the grid above, if you used gridData.getRowHeaders(0).getHeader(0).getName(), this method would return " "Books".

• getColHeaders(pos)
  Returns metric headers for a given column, where pos is the index of the column, in the format mstrmojo.models.templates.Headers.
  Returns: Array of COLUMN HEADER objects
  For example, using the grid above, if you usedgridData.getColHeaders(0).getHeader(0).getName(), this method would return "Revenue".

• getMetricValue(row,col)
  Returns the metric value for the specified row and column, in the format mstrmojo.models.templates.MetricValue.
  Returns: Integer
  For example, using the grid above, if you used gridData.getMetricValue(2,0).getValue(), this method would return "$1,121,696".

• isEmpty()
  Returns a value indicating whether the grid has any cells.
  Returns: Boolean
  For example, using the grid above, this method would return "False".

• getColumnHeaderData()
  Returns the header data for the columns.
  Returns: Array of objects
  For example, using the grid above, if you used gridData.getColumnHeaders(), this method would return an array of objects.

DataInterface has the following enumeration:

• ENUM_RAW_DATA_FORMAT
  Identifies the following formats for raw data:

1. • TREE
     This is the tree format expected by some D3 visualizations. 

mstrmojo.models.templates.Titles

Titles.js uses the following methods to get the count and value of  Title objects:

• Size()
  Returns the size of the array of Title objects.
  Returns: Integer
  For example, using the grid above, this method would return "2". 
• getTitle(pos)
  Returns the Title element for a given position in the array.  
  Returns: Title object
  For example, using the grid above, for a ROW TITLE, if you used gridData.getRowTitles().getTitle(0).getName(), this method would return "Category" .

mstrmojo.models.templates.Title

Title.js uses the following methods to get the values and properties for each Title object: 

• getHeaderValues()
  Returns the Header value for the Title.
  Returns: Header object
  For example, using the grid above, this method would return something like the line of code shown below:
  {"n":"Web","id":"h7;8D679D3811D3E4981000E787EC6DE8A4"}  
• getHeaderName(pos)
  Returns the name for a given Header
  Returns: String
  For example, using the grid above, for a ROW HEADER, if you used gridData.getRowHeaders().getTitle(0).getHeaderName(2), this method would return "Movies". 
• getheaderId(pos)
  Returns the ID for a given Header
  Returns: Integer
  For example, using the grid above, for a ROW HEADER, if you used gridData.getRowHeaders().getTitle(0).getHeaderId(1), this method would return the ID for "Electronics".   
• getForms()
  Returns the available forms for the Title.
  Returns: Array of objects
  For example, using the grid above, if you used gridData.getRowHeaders().getTitle(0).getForms, this method would return an array of form objects for the specified title. 
  
• getFormId()
  Returns the form ID for the Title.
  Returns: String
  For example, using the grid above, if you used gridData.getRowHeaders().getTitle(0).getFormId(), this method would return the ID for the specified title. 
• getFormType()
  Returns the form type for the Title.
  Returns: Integer
  For example, using the grid above, this method would return one of the following values:
      -1    for metric
     21    for attribute form 
• getName()
  Returns the name for the Title.
  Returns: String
  For example, using the grid above, for a ROW TITLE, this method would return "Category" or " Year".

mstrmojo.models.templates.Headers

Headers.js uses the following methods to get the count and value of  Headerobjects: 

• Size()
  Returns the size of the array of Header objects.
  Returns: Integer
  For example, using the grid above, this method would return "2".
• getHeader(pos)
  Returns the Header element for a given position in the array.  
  Returns: Header object
  For example, using the grid above, for a ROW HEADER, if you used gridData.getRowHeader(0).getHeader(4), this method would return "Electronics".
  mstrmojo.models.templates.Header

mstrmojo.models.templates.Header

Header.js uses the following methods to get the values and properties for each Header object:

• getName()  
  Returns the Header value.
  Returns: String
  For example, using the grid above, for a COLUMN HEADER, this method would return  "Revenue"or "Sales Rank".

• getElementId()  
  Returns the element ID for the Header.
  Returns: String
  For example, using the grid above, if you used gridData.getColHeaders(0).getHeader(1).getElementId(), this method would return the element ID for Books.

• getObjectId()  
  Returns the object ID for the Header.
  Returns:String
  For example, using the grid above, if you used gridData.getColHeaders(0).getHeader(1).getObjectId(),  this method would return "4C051D7511D3E877C000B3B2D86C964F".

• getElementIndex()  
  Returns the index of the Header in the Headers array.
  Returns: Integer
  For example, using the grid above, if you used gridData.getColHeaders(0).getHeader(1).getElementIndex(),  this method would return "1". (In this case, the value returned is the same as the value you passed in to getHeader.)

• isTotal()  
  Returns a value indicating whether this is the Header for total value.
  Returns: Boolean
  For example, using the grid above, this method would return "False".

mstrmojo.models.templates.MetricValue

MetricValue.js uses the following methods to get the values and properties for each MetricValue object: 

• getValue()
  Returns the value of the metric, with number formatting.
  Returns: String
  For example, using the grid above, this method would return something like "$650,192" or "9". 
• getRawValue()
  Returns the raw value of the metric, without number formatting.
  Returns: Integer
  For example, using the grid above, this method would return something like "650191.649999".