Version 2021

Enable the Selection of Attribute Elements

The MicroStrategy 2021 Update 3 release exposes attribute element selection within dossiers. This provides end-users with the ability to conveniently select attribute elements in visualizations in an embedding way. To provide continuity with our existing APIs and enable embedded applications to take advantage of this new design concept, we have updated existing endpoints and provided new embedding SDK functions.

Embedding Behavior Details

  1. Provide a JavaScript function call to support programmatic selecting of attribute elements in visualizations. This involves the following:

    1. Select attribute elements from a single visualization after the dossier is rendered.

    2. Select attribute elements in multiple visualizations on the initial loading of the dossier.

  2. Provide a JavaScript function call to support programmatic retrieval of available elements in a visualization.

  3. Provide a JavaScript event handler to notify the parent application when the attribute element selection is changed. Incorporate the ability to register and unregister events for a callback. This enables the parent application to know when the attribute element selection is changed and provide information about the newly selected attribute elements.

Embedding SDK APIs and Examples

  1. API for attribute element selection in a dossier

    Function

    Dossier.selectVizElement(props)

    The Dossier object created using microstrategy.dossier.create(props). See Methods and Properties for an Embedded Dossier for more information.

    Input Parameters

    Parameter Name Description Data Type Required? Sample
    props

    Parameters include visualization key, selection action, and selection data.

    		 Object Yes See the JSON below.

    Request 

    {
    "vizKey": "W64",
    "action": "replace", // not required. available values: replace, add, remove. default: replace
    "selection": {
        "attributeElements": [
            {
                "attribute": {
                    "id": "8D679D3611D3E4981000E787EC6DE8A4",
                    "name": "Category" // Not required
                },
                "elements": [
                    {
                        "id": "h6;8D679D3611D3E4981000E787EC6DE8A4",
                        "name": "Spring 2012" // Not required
                    }
                ]
            }
        ]
    }
}

    Response

    This API returns a promise object, similar to the one shown below.

    myDossier && myDossier.selectVizElement({
  "vizKey": "K52",
  "action": "replace",
  "selection": ...,
}).then(() => {
  ...
}).catch(error => {
  ...
})

    Since the target state is specified in the API parameters, the callback parameters for the resolve case are not necessary.

    Parameter Name Data Type Example Comments
    error

    Error object

    		 new Error(“invalid operation!“) See API Errors for more information.

  2. API for selecting attribute elements in multiple visualizations on initial dossier load

    Function

    microstrategy.dossier.create(props)

    Input Parameters

    An optional visualizationSelectedElements field has been added to the props object in 2021 Update 3. This field is an array that contains objects for each visualization attribute element selection. See Methods and Properties for an Embedded Dossier for more information about the fields in the props input parameter.

    Parameter Name Description Data Type Required? Default Value
    props.visualizationSelectedElements[i].visualizationkey

    The visualization node key input by you.

    		 String Yes N/A

    props.visualizationSelectedElements[i].action

    Set to "replace", "add", or "remove".

    String

    No

    replace
    props.visualizationSelectedElements[i].selection Selected attribute elements in the visualization Object Yes N/A

    Example:

    microstrategy.dossier.create({  
  ...
  "visualizationSelectedElements": [{
    "visualizationkey": "K52",
    "selection": {
      "attributeElements": [{
        "attribute": {
          "id": "8D679D3611D3E4981000E787EC6DE8A4",
          "name": "Category"
        },
        "elements": [{
          "id": "h6;8D679D3611D3E4981000E787EC6DE8A4",
          "name": "Spring 2012"
        }]
      }]
    }
  }]
})

    If you do not enter a value for visualizationSelectedElements, the dossier runs using the old behavior and no new attribute elements are selected in the visualization.

    Response

    This API returns a dossier promise object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs.

    var placeholderDiv = document.getElementById("dossierContainer");
var myDossier;
microstrategy.dossier.create({  
	...
}).then(function(dossier){
    myDossier = dossier;
    myDossier.goToNextPage();
    ...
});

  3. API for getting available elements

    Function

    Dossier.getAvailableElements(visKey)

    Input Parameters

    Parameter Name Data Type Example Description Required?
    visKey String "K52" The visualization node key. It is the result of the getCurrentPageVisualizationList API. Yes

    Response

    This API returns a promise object, similar to the one below.

    myDossier && myDossier.getAvailableElements(visKey).then(availableElements => {
  ...
}).catch(error => {
  ...
})

    The callback parameters for this promise object are shown below.

    Parameter Name Data Type Example Comments
    availableElements Object 
    [
  {
    "attribute": {
      "id": "8D679D3611D3E4981000E787EC6DE8A4",
      "name": "Category"
    },
    "elements": [
      {
        "id": "h6;8D679D3611D3E4981000E787EC6DE8A4",
        "name": "Spring 2012"
      }
    ]
  }
]
    		The data is returned in an array, since there may be instances in which the data in several visualizations are changed at the same time.

    error

    Error object

    new Error(“invalid operation!“)

     

  4. Callback for monitoring the changing of visualization elements

    5. In some instances, the available elements may change when visualization data is changed by a user’s manual actions. An onVisualizationElementsChanged event monitors this action and enables the user to update their available elements immediately when the data is changed.

    Event Name

    onVisualizationElementsChanged

    Callback Format

    The following code example includes registerEventHandler, which is an existing API.

    myDossier && myDossier.registerEventHandler('onVisualizationElementsChanged', function(availableElements){
  ...      // The handling logic after getting these available elements
});

    The callback parameter's availableElements are shown below.

    [{
  "visualizationKey": "K52",
  "attributeElements": [
    {
      "attribute": {
        "id": "8D679D3611D3E4981000E787EC6DE8A4",
        "name": "Category"
      },
      "elements": [
        {
          "id": "h6;8D679D3611D3E4981000E787EC6DE8A4",
          "name": "Spring 2012"
        }
      ]
    }
  ]  
}]

API Errors

Since you cannot set the callback parameters, it’s impossible for these parameters to produce errors. When an error occurs for other reasons, the embedding API returns a promise object that in turn returns an error object in rejected cases. The possible errors are shown below.

Related APIs Error Category Handling Module Error Case Error Message
Dossier.selectVizElement(props)

 

 

 

 Invalid input

 

 

 Embedding SDK

 

 The attribute or element ID in elements is missing. The “id“ field of some attribute or element is missing. Please provide valid values for it.

The attribute ID in elements isn’t a GUID.

The attribute id value ''{0}'' is not a GUID.
The action isn’t a valid value. Invalid input for Dossier.selectVizElement(props): data.action should match pattern "add|replace|remove"

Web Dossier

 

A required parameter is missed or it is not in the correct format.

Error when valid parameter for ${0}: ${1} should be have required property ‘${2}’
The action is not “replace“ and the current visualization selection mode is metric cell selection. Adding or removing to current metric selection is not supported.

Other

The visualization is a filter and the target visualization is loading, so elements could not be selected.

The viz view is not rendered yet. Please wait for several seconds...
Dossier.getAvailableElements(visKey)

 

 Invalid input

 

 Embedding SDK A required parameter is missed or it is not in the correct format. Error when valid parameter for ${0}: ${1} should be have required property ‘${2}’

Web Dossier

The visKey isn’t a valid visualization key or it is not in the current page/panelstack

There isn’t a visualization whose key is “${0}“. Please check whether your input visKey is correct.
microstrategy.dossier.create(props)

 

 Invalid input

 

 Embedding SDK A required parameter is missed or it is not in the correct format. Error when valid parameter for ${0}: ${1} should be have required property ‘${2}’

Web Dossier

The visKey isn’t a valid visualization key or it is not in the current page/panelstack

There isn’t a visualization whose key is “${0}“. Please check whether your input visKey is correct.