Version 2021

Methods and Properties for an Embedded Dossier

This topic covers a method and corresponding properties for embedding a dossier, as well as a method to remove an embedded dossier.

Method and Properties for Embedding a Dossier

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? Default Value Sample
placeholder

Reference for the container <div>.

 Yes    

url

or

serverURL

application ID

objectID

pageKey

url refers to the full URL of the dossier to embed.

There are two ways to configure the URL to embed the dossier in Library:

  • Use the full URL

  • Build the URL using:

    serverURL + '/app/' + applicationID + '/' + objectID + '/' + pageKey

1.url is required

2. serverURL, application ID, and objectID are required, while pageKey is optional.

 
Copy 
microstrategy.dossier.create({
    placeholder: placeholderDiv,
    url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
});
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 a style: style="height: $(containerHeight)".

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

 No 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.

No

800px

 
custom
Authentication
Type		 Specifies the token type returned by the getLoginToken function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. No Custom Authentication Type.IDENTITY_ TOKEN  

disable
Notification

Specifies whether to display messages, such as Add to library in the notification bar. If this property is set to true, message do not appear in the notification bar.

Manipulations are not affected by this property. They persist in the same way as the default dossier status.

No

true

 
dockedComment

Use this property to configure the Comment panel on the UI.

dockedPosition
Only "left" or "right" is accepted as the position of the docked panel.

canClose
Boolean. If set to false, the panel is forced to appear.

dockChangeable
Boolean. If set to false, the dock/pin button is hidden. The docked status of this panel is controlled by isDocked.

isDocked
Boolean. This configures whether the panel is docked.

 No null
The default status is used on the dossier.

Docked Comment:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  dockedComment: {
    dockedPosition: "left",
    canClose: false,
    dockChangeable: false,
    isDocked: true
  }
})

dockedFilter

Use this property to configure the Filter panel on the UI.

dockedPosition
Only "left" or "right" is accepted as the position of the docked panel.

canClose

Boolean. If set to false, the panel is forced to appear.

dockChangeable

Boolean. If set to false, the dock/pin button is hidden. The docked status of this panel is controlled by isDocked.

isDocked

Boolean. This configures whether the panel is docked.

No

null
The default status is used on the dossier.

Docked Filter:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  dockedFilter: {
    dockedPosition: "left",
    canClose: false,
    dockChangeable: false,
    isDocked: true
  }
}
dockedTOC

Use this property to configure the Table of Contents panel on the UI.

dockedPosition
Only "left" or "right" is accepted as the position of the docked panel.

theme
Only "dark" or "light" theme is accepted.

canClose
Boolean. If set to false, the panel is forced to appear.

dockChangeable

Boolean. If set to false, the dock/pin button is hidden. The docked status of this panel is controlled by isDocked.

isDocked

Boolean. This configures whether the panel is docked.

 

 No null
The default status is used on the dossier.

Docked TOC:

Copy 
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

Use this property to customize the dossier feature on the UI.

readonly
Enable or disable context menus. If this property is set to true, all context menus are disabled. This includes the visualization right-mouse click context menu and the context menu at the top right of the visualization, that contains such options as Export.

No

null
The default status is used on the dossier.

dossierFeature:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  dossierFeature: {
    readonly: true
  }
})

enable
Collaboration

Use this Boolean property to enable or disable collaboration-related controls of Library.

No

null
The default status is used on the dossier.

enableCollaboration:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  enableCollaboration: true
})

enableCustom
Authentication

Specifies whether custom authentication is enabled.

No

false
User needs to log in from the default login page.

 

enableResponsive

Specifies whether to enable responsive design.

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

No

false

 

filterFeature

Use this property to customize the filter functionality on the UI. All detailed properties below are Boolean.

enabled
Enable or disable filter features.

edit
Show or hide the filter edit function. Enable or disable editing on the filter panel.

summary
Show or hide the filter summary bar.

No

null
The default status is used on the dossier.

Filter Feature:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  filterFeature: {
    enabled: true,
    edit: false,
    summary: true
  }
})
filters

Use this property to apply attribute selection or attribute search filters during the execution of a dossier. It supports passing multiple filter definitions with multiple selectors.

Filter Format:

[{   "key": "string",
  "name": "string",
  "selections": [{
    "id": "string",
    "name": "string"
  }]
}]

Filter Key/Filter Name
Identifies the filter. At least one of the two is required.

Element ID/Element Name
Identifies the filter. At least one of the two is required.

Only attribute selection filters and attribute search filters are supported. Attribute slider, calendar, and metric filters are not supported.

 No null
No filters are applied during execution

Filter Key with Element ID:

Copy 
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:

Copy 
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 authorization token (authToken) or the identity token (identityToken) The token type is specified by the customAuthenticationType property.

No

See the sample code in the next column for the default implementation of this function.

When customAuthenticationType is set to
CustomAuthenticationType,AUTH_TOKEN
the following sample demonstrates how to send a
fetch request to get authToken with your
credentials. You can do this using an
XMLHttpRequest, if your browser does not
support fetch.

Copy 
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 set to
CustomAuthenticationType. IDENTITY_TOKEN, you need to add a component to your web server. Refer to Use Custom Authentication for more information.
instance

Use this property to specify the instance information for the embedded dossier..

mid
This instance ID.

id
Instance ID for a report-based in-memory dossier

partialManipulation

Boolean that indicates the personal view partial execution status. If this is set to true, a personal view is in partial execution

status
The personal view partial execution status. If this is true, it indicates a personal view is in partial execution.

 

 No null

Pass existing instance:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  instance: {
    mid: ’CC9F19A411EA1084548F0080EF05D751’,
    status: 1
  }
})

 
navigationBar

edit
Show or hide the edit icon. Disabled by default.

enabled
Enable or disable the navigation bar.

gotoLibrary
Show or hide the gotoLibrary icon.

title
Show or hide the dossier title.

toc
Show or hide the TOC icon.

reset
Show or hide the reset icon.

reprompt
Show or hide the reprompt icon

share
Show or hide the share icon

comment
Show or hide the comment icon.

notification
Show or hide the notification icon.

filter
Show or hide the filter icon.

options
Show or hide the options icon.

search
Show or hide the search icon.

bookmark
Show or hide the bookmark icon.

 No null
The navigation bar is hidden by default

Navigation Bar Configuration:

Copy 
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  navigationBar: {
    edit: false,
    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

Use this property to customize the Options feature on the UI. All detailed properties below are Boolean.

enabled
Enable or disable the options features.

help
Show or hide help functionality.

logout
Show or hide the logout functionality.

manage
Show or hide manage functionality.

showTutorials
Show or hide tutorial functionality.

 

No

null
The default status is used on the dossier.

Options Feature:

Copy 
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

Use this property to customize the Share feature on the UI. All detailed properties below are Boolean.

enabled
Enable or disable share features.

invite
Show or hide invite functionality.

link
Show or hide link functionality.

email
Show or hide email functionality.

export
Show or hide export functionality.

download
Show or hide download functionality.

shareDossier
Show or hide the shareDossier function.

subscribe
Show or hide all entries for a subscription.

No

null
The default status is used on the dossier.

Share Feature:

Copy 
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
  }
})

Subscribe Feature:
MicroStrategy only supports fetching multi-content subscriptions for Library and Workstation clients. To use this functionality, you must use the correct applicationType of 35 in the login function as shown below.

Copy 
function login() {
        var options = {
            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 ,// Login as guest user.
                username: 'administrator',
                password: '',

                applicationType: 35 // add this
            })
        };
        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);
            });
    }

                                                            		
                                                        

                                                        

                                                            smartBanner
                                                            
                                                                
Use this property 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 and login pages, but not 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.

                                                            		
                                                            No
                                                            
                                                                
false
                                                                    
The smart banner does not appear by default.

                                                            		
                                                            
                                                                
Smart Banner:

                                                                

                                                                    
Copy
                                                                        
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  smartBanner: false
})

                                                                        

                                                                    

                                                                

                                                                
 

                                                            		
                                                        

                                                        

                                                            
                                                                
tocFeature

                                                            		
                                                            
                                                                
Use this property to customize the TOC feature on the UI.

                                                                
enabled
                                                                    
Use a Boolean to enable or disable TOC features.

                                                            		
                                                            
                                                                
No

                                                            		
                                                            
                                                                
null
                                                                    
The default status is used on the dossier.

                                                            		
                                                            
                                                                
TOC Feature:

                                                                

                                                                    
Copy
                                                                        
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  tocFeature: {
    enabled: true
  }
})

                                                                        

                                                                    

                                                                

                                                            		
                                                        

                                                        

                                                            uiMessage
                                                            
                                                                
Use this property to customize the message features on the UI. If disableNotification is set to true, this property is ignored and all messages are hidden. All detailed properties below are Boolean.

                                                                
enabled
                                                                    
Enable or disable all messages.

                                                                
addToLibrary
                                                                    
Show or hide the addToLibrary message.

                                                            		
                                                            No
                                                            
                                                                
null
                                                                    
Depends on the default status of the dossier and the value in the disableNotification property.

                                                            		
                                                            
                                                                
UI Message:

                                                                
Copy
                                                                    
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  uiMessage: {
    enabled: true,
    addToLibrary: false
  }
})

                                                                    

                                                                

                                                            		
                                                        

                                                        

                                                            
                                                                
visibleTutorials

                                                            		
                                                            
                                                                
Use this property to customize the visibility of tutorials. All detailed properties below are Boolean.

                                                                
welcome
                                                                    
Enable or disable the welcome tutorial.

                                                                
library
                                                                    
Enable or disable the Library tutorial.

                                                                
dossier
                                                                    
Enable or disable the dossier tutorial.

                                                                
notification
                                                                    
Enable or disable the notification tutorial.

                                                                
If the welcome tutorial is enabled, the Library tutorial is also automatically enabled.

                                                            		
                                                            
                                                                
No

                                                            		
                                                            
                                                                
null
                                                                    
The default status is used on the dossier.

                                                            		
                                                            
                                                                
Visible Tutorials:

                                                                
Copy
                                                                    
microstrategy.dossier.create({
  placeholder: placeholderDiv,
  url: http://{host}:{port}/{Library}/app/{ProjectID}/{DossierID},
  visibleTutorials: {
    library: true,
    welcome: false,
    dossier: true,
    notification: false
  }
})

                                                                    

                                                                

                                                            		
                                                        

                                                        

                                                            visualizationAppearances
                                                            
                                                            
                                                                
Use this property to assign which visualization needs to be resized in the initial loading process, and whether the user could see the resize button of the visualization.
See Embed a Single Visualization for more information.


                                                                
Format:
[{
    "visualizationkey": "K52",
    "size": "maximized",
    "resizeButtonVisible": false
}]

                                                                
visualizationKey
                                                                    
The visualization node key input by you.

                                                                
size
                                                                    
Set to "normal" or "maximized", to restore or maximize this visualization.

                                                                
resizeButtonVisible
                                                                    
Determines whether the resize button is visible. If a Boolean is not provided, the visibility remains the same.

                                                            		
                                                            No
                                                            null
                                                                
No visualization needs to be maximized or restored during initial loading



                                                            
                                                                
 

                                                            		
                                                        

                                                    
                                                

                                            

                                            
Method for Removing an Embedded Dossier

                                            

                                                

                                                    
                                                    
                                                    
                                                    
                                                        

                                                            Method
                                                            Description
                                                            Return Value
                                                        

                                                    
                                                    
                                                        

                                                            
                                                                
microstrategy.dossier.destroy({placeholder: placeholderDiv});
                                                                

                                                            		
                                                            
                                                                
Destroy the embedded dossier in the same placeholder you used when calling microstrategy.dossier.create.

                                                            		
                                                            
                                                                
null