Version 2021

Code Sample: Embed a Dossier

To help you get started embedding MicroStrategy content into a web application or portal, we have provided a sample that embeds a MicroStrategy dossier into an HTML page. By design, this is a simple sample. However, once the dossier is embedded, the sample can be extended by adding other functionality supported by the Embedding API, such as controlling navigation, retrieving and applying filters, setting properties, and managing events like page changes.

To set up the sample, follow the steps below.

  1. Deploy the MicroStrategyLibrary web application locally or in a Cloud instance.
  2. Open Tomcat or another web application server and create a folder called EmbeddedDemo in the webapps directory.

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

  3. Create an HTML file in your favorite IDE or text editor, using the sample HTML content shown below, and save it in the EmbeddedDemo folder.

    To make it easier for you, we have provided a sample HTML file that has the basic content described below. Simply download the file, extract its contents, and use it as the basis of your code as you follow the steps.

    In the sample code, you reference the embeddinglib.js file, which contains the Embedding API, as the value of the src attribute in the first <script> node. This javascript file is included in the MicroStrategyLibrary web application. You need to update the value for url to reference a dossier in your environment; you can obtain this value by running a dossier in MicroStrategyLibrary and copying the URL.

    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8">
        <title&gt;&lt;/title>
        <script type="text/javascript" src="https://demo.microstrategy.com/MicroStrategyLibrary/javascript/embeddinglib.js"></script>
      </head>
      <body onload="load()">
        <div id="mydossier"></div>
        <script type="text/javascript">
          var myDossier;
          function load() {
            var container = document.getElementById("mydossier"),
              url = "https://demo.microstrategy.com/MicroStrategyLibrary/app/EC70648611E7A2F962E90080EFD58751/F6252B9211E7B348312C0080EF55DB6A/K53--K46";
            microstrategy.dossier.create({
              url: url,
              enableResponsive: true,
              placeholder: container,
              containerHeight: '800px'
            });
          };
        </script>
      </body>
    </html>
  4. Save your HTML file.
  5. Open your HTML file in a browser to view the embedded dossier. Because you did not integrate single sign-on (SSO), you will be prompted for credentials. In the following steps, you will learn how to enable single sign-on.

  6. Now, you will add code to enable single sign-on. Open your HTML file again in your favorite IDE or text editor. In the next three steps, you will add two properties and a function call to the microstrategy.dossier.create() method call.
  7. First, you add a property to allow custom authentication to be used and set it to "true": enableCustomAuthentication:true.

    function load(){
      var container = document.getElementById("mydossier"), 
          url = "http://<YOUR-SERVER>/MicroStrategyLibrary/app/<projectID>/<dossierID>";
      microstrategy.dossier.create({
        url: url,
        enableCustomAuthentication:true,
        ...

    The enableCustomAuthenticationproperty is an optional parameter for the create method. If it is set to "false", the user will be prompted for credentials by the standard MicroStrategy Library login page.

  8. Next, you add a property to indicate the token type and set it to the enumeration value for the authToken: customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN.

    function load(){
      var container = document.getElementById("mydossier"), 
          url = "http://<YOUR-SERVER>/MicroStrategyLibrary/app/<projectID>/<dossierID>";
      microstrategy.dossier.create({
        url: url,
        enableCustomAuthentication: true,
        customAuthenticationType:microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
        ...

    There are two token types, authToken and identityToken, which are both returned in the response of POST /auth/login. However, the identity token should be used only if the POST /auth/login call is made within a different HTTP session. In this sample, you are making the REST API request to authenticate as Guest within the same HTTP session so you simply need to pass the auth token. There is an enumeration for this field found in the Embedded API, microstrategy.dossier.CustomAuthenticationType.

  9. Finally, you add a function call, getIdentityToken(), to the microstrategy.dossier.create() method.
     function load(){
        var container = document.getElementById("mydossier"), 
          url = "http://<YOUR-SERVER>/MicroStrategyLibrary/app/<projectID>/<dossierID>";
        microstrategy.dossier.create({
          url: url,
          enableCustomAuthentication:true,
          // The following function is our default implementation. Users can provide their own implementation.
          getIdentityToken: function(){
            // Write a javascript call that returns a Promise. This Promise should contain the x-mstr-identityToken
          },
          placeholder: container
        });
      };      
    </script>

    The getIdentityToken() function returns a Promise, which should contain the x-mstr-identityToken header value returned from POST /auth/login. If you created a new identity token, the Promise should contain the x-mstr-identityToken header value returned from POST /auth/identityToken.

    • Within the javascript call created above, there needs to be a call to the POST /auth/login REST endpoint to get the x-mstr-identityToken header value. This can be done with a javascript XHR call using XMLHTTPRequest(). To understand the parameters that can be sent for this endpoint, see the MicroStrategy REST server Swagger documentation. The sample code below provides an example of calling POST /auth/login using Curl:
      curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic bXN0cjpmUGg3MDdxdTVERHI=' -d '{\
        "loginMode":8
      }' 'https://env-61259.customer.cloud.microstrategy.com/MicroStrategyLibrary/api/auth/login'
      
    • The sample code below illustrates how to add a method call within getIdentityToken() that accepts information about the request being made and returns a Promise.
      var mydossier;
      function load() {
        var container = document.getElementById("mydossier"),
            url = "http://<YOUR-SERVER>/MicroStrategyLibrary/app/<projectID>/<dossierID>";
        microstrategy.dossier.create({
          url: url,
          enableCustomAuthentication: true,
          enableResponsive: true,
          customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
          placeholder: container,
          getLoginToken: function() {
            return getXHRRequestPromise('http://localhost:8080/MicroStrategyLibrary/api/auth/login', postData, 'POST','application/json', 'x-mstr-authToken').then(function(authToken){
              return authToken;
            });
          }
        });
      };
  10. Below is an example of the getXHRRequestPromise() method used in the code shown above.

    /* Minimal information necessary to authenticate with Guest(Anonymous) authentication */
                        
    var postData = {
      loginMode: 8
    }
     
    function getXHRRequestPromise(url, body, method, contentType, desiredHeader) {
      return new Promise(function(resolve, reject) {
        var xhr = new XMLHttpRequest();
        xhr.open(method, url);
        xhr.setRequestHeader('Content-Type', 'application/json');
        xhr.setRequestHeader("Accept", "application/json");
        xhr.send(JSON.stringify(body));
        xhr.onreadystatechange = function() {
          if (xhr.readyState === 2) {
            resolve(xhr.getResponseHeader(desiredHeader));
          } else {
            reject({
              status: this.status,
              statusText: xhr.statusText
            });
          }
        };
      });
    };
  11. Once the getXHRRequestPromise() method has been completed, save your HTML file and open it in a browser. Because single sign-on (SSO) is enabled, the authentication process is done behind the scenes, and the login screen is not displayed. The embedded dossier is seamlessly displayed in the browser.

    When you make an XHR request for POST /auth/login, you only need to wait until the response headers are returned. The expected status code will be 204 (Success no content). Review the documentation on XMLHTTPRequest.readyState to understand what is necessary to obtain the request header (hint status = 2). If the dossier does not render on the page, you can use the browser developer tools to review any exceptions or errors being thrown.