Version: 2019

Setting properties for an embedded dossier

When you embed a dossier, you can set properties to customize the user interface, the features that are available or visible, and authentication.

To help you get started, we have provided a sample application that sets properties on an embedded dossier, followed by a table that lists and describes each property that you can set. You use the create(props) method under the microstrategy.dossier namespace to set properties. The props parameter contains optional key:value pairs to customize the UI, features, and authentication, in addition to the required key:value pairs that define the URL where the dossier is located and the ID of the <div> placeholder where the iFrame containing the dossier instance will be created.

This sample is provided as an HTML file, which must be hosted on a web server. It cannot be run as a standalone file.

Sample application

The following sample shows how to leverage the Embedding API to add properties to an embedded dossier. You use the sample application that is provided for you and configure the code for your environment.

To deploy this sample in your environment, either:

  1. Save the code sample below to an HTML file hosted on the same web application server as the MicroStrategy Library application.

    If the application server is different from the server running the MicroStrategyLibrary application, you may need to perform additional configuration to support Cross-Origin Requests (CORS).

                or

    Download the HTML file provided for you. This file contains the sample code shown below.

  2. Configure the HTML file for your environment.

    1. Edit the value of the src attribute in the <script> tag shown below so that it points to the embeddinglib.js within the javascript folder of your MicroStrategyLibrary application.

      <!-- Replace path to point to the embeddingLib in your environment -->

      <script src="https://<YOUR_SERVER>/MicroStrategyLibrary/javascript/embeddinglib.js"></script>

      <script>

    2. Set the property variables located between the tags shown below.

      //BEGIN CONFIG PROPERTY VARIABLES -----------------------------------------

        var BASE_URL = "https://<YOUR_SERVER>/MicroStrategyLibrary";

        var userName = "<USER_NAME>";

        var passWord = "<PASSWORD>";

        var projectId = "<PROJECT_ID>";

        var dossierId = "<DOSSIER_ID>";

        var nav = {

          enabled: true

        };

        var filterList = [

          {

            "name": "Category", //You can change to the actual attribute name.

            "selections": [

              {"name":"Books"} //You can change to the actual attribute element name.

            ]

          }

        ];

      //END CONFIG PROPERTY VARIABLES ------------------------------------------

Code for sample application

<!DOCTYPE html>

<html lang="en">

<head>

  <meta charset="UTF-8">

  <title>Simple Sample for Setting Properties</title>

  <!-- Replace path to point to the embeddingLib in your environment -->

  <script type="text/javascript" src="https://<YOUR_SERVER>/MicroStrategyLibrary/javascript/embeddinglib.js"></script>

</head>

<body onload="showDossier()">

<div id="myDossier"></div>

<script type="text/javascript">

//BEGIN CONFIG PROPERTY VARIABLES ------------------------------------------------

  var BASE_URL = "https://<YOUR_SERVER>/MicroStrategyLibrary";

  var userName = "<USER_NAME>";

  var passWord = "<PASSWORD>";

  var projectId = "<PROJECT_ID>";

  var dossierId = "<DOSSIER_ID>";

  var nav = {

    enabled: true

  };

  var filterList = [

    {

      "name": "Category", //You can change to the actual attribute name.

      "selections": [

        {"name":"Books"} //You can change to the actual attribute element name.

      ]

    }

  ];

//END CONFIG PROPERTY VARIABLES -------------------------------------------------

  function showDossier() {

    var placeHolderDiv = document.getElementById("myDossier");

    var dossierUrl = BASE_URL +'/app/'+ projectId + '/' + dossierId;

    microstrategy.dossier.create({

      // set properties

      placeholder: placeHolderDiv,

      url: dossierUrl,

      enableCustomAuthentication: true,

      enableResponsive: true,

      customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,

      getLoginToken: login,

      navigationBar: nav, //enable navigation bar

      filters: filterList //pass filter during dossier execution

    });

  }

  function login() {

    var options = {

      method: 'POST',

      credentials: 'include', //include cookie

      mode: 'cors', //set as CORS mode for cross origin resource sharing

      headers: {'Content-Type': 'application/json'},

      body: JSON.stringify({

        loginMode: 1, //standard authentication mode

        username: userName,

        password: passWord

      })

    };

    return fetch(BASE_URL + '/api/auth/login', options).then(function (response) {

      if (response.ok) {

        return response.headers.get('x-mstr-authToken');

      } else {

        response.json().then(function(json) {

          console.log(json);

        });

      }

    }).catch(function (error) {

      console.log(error);

    });

  }

</script>

</body>

</html>

Properties

When you embed a MicroStrategy dossier into a web page, you use the create(props) method under the microstrategy.dossier namespace.

Method Description Return Value

microstrategy.dossier.create(props);

This method creates an iFrame on the web page (in the location specified by the placeholder property) and inserts a link to the URL (specified by the url property) where the dossier to be embedded is located.

This method returns a promise, which is resolved when the dossier instance is created.

The props parameter contains required key:value pairs that define the URL where the dossier is located and the ID of the <div> placeholder where the iFrame containing the dossier instance will be created. It can also contain other optional key:value pairs to customize the UI, features, and authentication.

The props parameter can contain the following key:value pairs:

Property Name Description Required / Optional Default Value Sample

placeholder

Reference for the container <div>

Required

   

url

URL of the dossier to be embedded

 Required

   
containerHeight

Sets the height of the placeholder.

  • If the style of the placeholder has a height value, the containerHeight property is ignored.
  • If the enableResponsive property is set to "True", the containerWidth property is ignored and the containerHeight property takes effect.

The containerHeight property is applied as style: style="height: ${containerHeight}".

You should not set the containerHeight property to 100% if the container <div> has no parent container, but is attached directly to the <body>.

Optional 600px  

containerWidth

Sets the width of the placeholder.

  • If the style of the placeholder has a width value, the containerWidth property is ignored.
  • If the enableResponsive property is set to "True", the containerWidth property is ignored and the width is adjusted to fit the viewport.
Optional 800px  
customAuthenticationType

Specifies the token type returned by the getLoginToken function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration:

  • CustomAuthenticationType.IDENTITY_TOKEN
  • CustomAuthenticationType.AUTH_TOKEN

You access this enumeration with microstrategy.dossier.CustomAuthenticationType.

Optional CustomAuthenticationType.IDENTITY_TOKEN  

disableNotification

Beginning in version 11.0:

  • Specifies whether to display messages, such as "Add to library", in the notification bar.

    If this property is set to "true", messages will not be displayed in the notification bar.

  • Manipulations are not affected by this property; they will be persisted the same way as default dossier status.

In versions prior to 11.0:

  • Specifies whether to display messages, such as "Add to library", in the notification bar and to persist manipulations, such as navigation and changing filters.

    If this property is set to "true", messages will not be displayed in the notification bar and manipulations will not be persisted.

Optional True  
dockedComment

This property is used to configure the Comment panel on the UI.

Detailed properties:

  • dockedPosition:
    "left" or "right" position of docked panel
    (Only left or right is accepted.)
  • canClose:
    boolean
    (If set to "false", panel is forced to be displayed.)
  • dockChangeable:
    boolean
    (If set to "false", dock/pin button is hidden. The docked status of this panel is controlled by isDocked.)
  • isDocked:
    boolean
    (Configures whether this panel is docked.)
Optional null
(default status will be used on Dossier)

Docked comment

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  dockedComment: {

    dockedPosition: "left",

    canClose: false,

    dockChangeable: false,

    isDocked: true

  }

})

dockedFilter

This property is used to configure the Filter panel on the UI.

Detailed properties:

  • dockedPosition:
    "left" or "right" position of docked panel
    (Only left or right is accepted.)
  • canClose:
    boolean
    (If set to "false", panel is always displayed.)
  • dockChangeable:
    boolean
    (If set to "false", dock/pin button is hidden. The docked status of this panel is controlled by isDocked.)
  • isDocked:
    boolean
    (Configures whether this panel is docked.)
Optional null
(default status will be used on Dossier)

Docked filter

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  dockedFilter: {

    dockedPosition: "left",

    canClose: false,

    dockChangeable: false,

    isDocked: true

  }

})

dockedTOC

This property is used to configure the Table of Contents (TOC) panel on the UI.

Detailed properties:

  • dockedPosition:
    "left" or "right" position of docked panel
    (Only left or right is accepted.)
  • theme:
    "dark" or "light" theme
    (Only dark or light is accepted.)
  • canClose:
    boolean
    (If set to "false", panel is always displayed.)
  • dockChangeable:
    boolean
    (If set to "false", dock/pin button is hidden. The docked status of this panel is controlled by isDocked.)
  • isDocked:
    boolean
    (Configures whether this panel is docked.)
Optional null
(default status will be used on Dossier)

Docked TOC

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  dockedTOC: {

    dockedPosition: "left",

    theme: "light",

    canClose: false,

    dockChangeable: false,

    isDocked: true

  }

})

dossierFeature

This property is used to customize the Dossier feature on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • readonly:
    Enable/disable context menus
    (When readonly is set to "true", all context menus are disabled, including the visualization right-mouse-click context menu and the context menu on the top right of the visualization (that has options like "Export".)
Optional null
(default status will be used on Dossier)

dossierFeature

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  dossierFeature: {

    readoOnly: true

  }

})

 

enableCollaboration

This property is used to enable or disable collaboration-related controls of Library.

Property type: Boolean

Optional null
(default status will be used on Dossier)

enableCollaboration

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  enableCollaboration: true

})

 

enableCustomAuthentication

Specifies whether custom authentication is enabled.

Optional

False

(User needs to log in from the default log-in page)

 

enableResponsive

Specifies whether responsive design is enabled.

When this is set to "true", the placeholder is adjusted to fit the width of the viewport and the existing width/height ratio is used to provide the height.

Optional

False

 
filterFeature

This property is used to customize the Filter feature on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • enabled:
    Enable/disable filter features
  • edit:
    Show/hide filter edit function, enable/disable edit on filter panel
  • summary:
    Show/hide filter summary bar
Optional null
(default status will be used on Dossier)

filter feature

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  filterFeature: {

    enabled: true,

    edit: false,

    summary: true

  }

})

filters

This property is used to apply attribute selection or attribute search filters during the execution of a dossier. It supports passing multiple filter definitions with multiple selections.

  • Filter format:

    [ {

      "key": "string",

      "name": "string",

      "selections": [ {

        "id": "string",

        "name": "string"

      } ]

    } ]

  • Filter key/Filter name:
    Used to identify the filter (at least one of them is required.)
  • Element ID/Element name
    Used to identify the filter selection value (at least one of them is required)

In 11.0, only attribute selection filters and attribute search filters are supported. Attribute slider, calendar, and metric filters are not supported.

Optional null
(no filters will be applied during execution)

Filter key with Element ID

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  filters: [{

    "key": "WC8587FF21995453CBE5F0B66702BF56F",

    "selections": [{

      "id":"h1;8D679D4111D3E4981000E787EC6DE8A4;20K and Under"

    }, {

      "id":"h2;8D679D4111D3E4981000E787EC6DE8A4;20K-30K"

    }, {

      "id":"h3;8D679D4111D3E4981000E787EC6DE8A4;30K-40K"

    }]

  }, {

    "key": "W7EE7B7046845417E9D7743799FE7C699",

    "selections": [{

      "id":"h4;8D679D4B11D3E4981000E787EC6DE8A4;Central"

    }, {

      "id":"h2;8D679D4B11D3E4981000E787EC6DE8A4;Mid-Atlantic"

    }]

  }]

})

Filter name with Element name

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  filters: [{

    "name": "Income Bracket",

    "selections": [{

      "name": "20K and Under"

    }, {

      "name": "20K-30K"

    }, {

      "name": "30K-40K"

    }]

  }]

})

 

getLoginToken

Specifies a function that returns a promise, which is resolved with either the authorization token (authToken) or the identity token (identityToken). The token type is specified by the customAuthenticationType property.

Optional See the sample code for the default implementation of this function.
  • When customAuthenticationType is CustomAuthenticationType.AUTH_TOKEN, the following sample code shows how to send a fetch request to get authToken with your credentials. You can achieve this using XMLHttpRequest if your browser does not support fetch.

    Sample code for getLoginToken on the Embedding SDK API

    microstrategy.dossier.create({

      placeholder: placeholderDiv,

      url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

      enableCustomerAuthentication: true,

      customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,

      //The following function is the default implementation. User can provide custom implementation.

      getLoginToken: function() {

        return fetch('http://{host}:{port}/{Library}/api/auth/login', {

          method: 'POST',

          credentials: 'include', //including cookie

          mode: 'cors', //setting as CORS mode for cross origin

          headers: {'Content-Type': 'application/json'},

          body: JSON.stringify({

            loginMode: 1 ,// Standard mode

            username: 'input your username',

            password: 'input your password'

          })

        }).then(function(response){

          if(response&&response.ok){

            return response.headers.get("X-MSTR-authToken");

          }

        });

      }

    })

  • When customAuthenticationType is CustomAuthenticationType.IDENTITY_TOKEN, you need to add a component on your web server. Refer to Custom authentication for more details on how to do this.

navigationBar

This property is used to customize the Navigation Bar on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • enabled:
    Enable/disable navigation bar
  • gotoLibrary:
    Show/hide gotoLibrary icon
  • title:
    Show/hide dossier title
  • toc:
    Show/hide toc icon
  • reset:
    Show/hide reset icon
  • reprompt:
    Show/hide reprompt icon
  • share:
    Show/hide share icon
  • comment:
    Show/hide comment icon
  • notification:
    Show/hide notification icon
  • filter:
    Show/hide filter icon
  • options:
    Show/hide options icon
  • search:
    Show/hide search icon
  • bookmark:
    Show/hide bookmark icon
Optional null
(navigation bar will be hidden by default)

Navigation bar configuration

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  navigationBar: {

    enabled: true,

    gotoLibrary: false,

    title: false,

    toc: true,

    reset: true,

    reprompt: false,

    share: false,

    comment: true,

    notification: false,

    filter: true,

    options: true,

    search: false,

    bookmark: true

  }

})

optionsFeature

This property is used to customize the Options feature on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • enabled:
    Enable/disable options features
  • help:
    Show/hide help function
  • logout:
    Show/hide logout function
  • manage:
    Show/hide manage function
  • showTutorials:
    Show/hide showTutorials function
Optional null
(default status will be used on Dossier)

options feature

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  optionsFeature: {

    enabled: true,

    help: false,

    logout: true,

    manage: false,

    showTutorials: true

  }

})

shareFeature

This property is used to customize the Share feature on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • enabled:
    Enable/disable share features
  • invite:
    Show/hide invite function
  • link:
    Show/hide link function
  • email:
    Show/hide email function
  • export:
    Show/hide export function
  • download:
    Show/hide download function
Optional null
(default status will be used on Dossier)

share feature

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  shareFeature: {

    enabled: true,

    invite: false,

    link: true,

    email: false,

    export: true,

    download: false

  }

})

smartBanner

This property is used to enable or disable the smart banner feature when a user opens an embedded dossier in a mobile browser.

This property is supported on the dossier page and the login page, but not on the Library page. (If credentials are not provided, the user is redirected to the login page and the property setting in the original URL remains in effect.)

Property type: Boolean

Optional

False

(default is not to display the smart banner)

smartBanner

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  smartBanner: false

})

tocFeature

This property is used to customize the TOC feature on the UI.

Detailed properties:
(All detailed properties are boolean.)

  • enabled:
    Enable/disable toc features
Optional null
(default status will be used on Dossier)

TOC feature

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  tocFeature: {

    enabled: true

  }

})

uiMessage

This property is used to customize the message feature on the UI.

If disableNotification is set to "true", this property is ignored and all messages are hidden.

Detailed properties
(All detailed properties are boolean.)

  • enabled:
    Enable/disable all messages
  • addToLibrary:
    Show/hide addToLibrary message
Optional null
(depends on its default status on Dossier and value of disableNotification property)

UI message

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  uiMessage: {

    enabled: true,

    addToLibrary: false

  }

})

visibleTutorials

This property is used to customize the visibility of tutorials

Detailed properties:
(All detailed properties are boolean.)

  • welcome:
    Enable/disable welcome tutorial
  • library:
    Enable/disable library tutorial
  • dossier:
    Enable/disable dossier tutorial
  • notification:
    Enable/disable notification tutorial

There is limitation that when the welcome tutorial is enabled, the library tutorial will also be enabled automatically.

Optional null
(default status will be used on Dossier)

visible tutorials

microstrategy.dossier.create({

  placeholder: placeholderDiv,

  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},

  visibleTutorials: {

    library: true,

    welcome: false,

    dossier: true,

    notification: false

  }

})