Author an Embedded Dossier

Embedding MicroStrategy content within critical business applications empowers users to make smarter decisions by taking advantage of the dossier development efforts that occur behind the scenes. To allow users to conveniently edit a dossier, the MicroStrategy 2021 Update 3 release exposes the authoring mode, whether it is during the initial load or in the view mode of the dossier.

Embedding Behavior Details

1. Change the microstrategy.dossier.create API to add new fields in its initialized parameter object in the following situations:

   1. When entering authoring mode when displaying the page.

   2. When hiding the Edit button when displaying the page in consumption mode.

2. Add the Dossier.switchToMode API to allow the switch from view mode to authoring mode.

3. Provide an event to notify the parent application when the dossier is saved or closed.

Authoring Mode Constraints

The Availability of Existing Embedding SDK APIs

In authoring mode, most dossier-related APIs are disabled as they are designed for the consumption dossier instance. The remaining APIs supported in authoring mode are shown below.

The other APIs are disabled in authoring mode. If a disabled API is called in authoring mode, an error is returned with the message, "The API ${funcName} isn't supported in the authoring mode!"

Events

To avoid unexpected events, except the newly added events (see the callback event API and example), you cannot receive embedding SDK events in authoring mode as they are designed for consumption mode.

Initial Parameters

The props parameter contains many fields. See Methods and Properties for an Embedded Dossier for more information.

The existing parameters can be roughly divided into three categories and their behaviors can be set with dossierRenderingMode = authoring.

• The parameters shared by both modes, for example, "URL", "serverURL", "applicationID", "objectID", and "placeholder". These parameters only involve the embedding framework and are effective on both modes.

• The parameters used for some UI customization in consumption mode, for example, navigationBar.enabled. You can still use these parameters with dossierRenderingMode = authoring, but their effects can only be seen when switching back to consumption mode.

• The parameters used for some extra dossier instance manipulation, for example, filter and visualizationAppearances. These parameters are implementations of some embedding SDK APIs (for example, filter-related functions in the dossier class and changeVisualizationSize) for the initial workflow. As these embedding SDK APIs are forbidden in authoring mode, you must also forbid these parameters in the initial parameter in authoring mode to keep the consistent behavior. A complete list of these parameters are shown below.

If you have set values for these fields when setting dossierRenderingMode = authoring, a dialog appears with the error message, "The fields ["instance", "filters", "visualizationAppearances", "visualizationSelectedElements"] are not allowed to be used when "dossierRenderingMode" is "authoring". Please remove these forbidden fields and try again."

Embedding SDK APIs and Examples

1. API for entering authoring mode or disabling authoring mode in the initial loading

   Function

   microstrategy.dossier.create(props)

   Input Parameters

   An optional props.dossierRenderingMode field has been added to the props object in 2021 Update 3. The props parameter contains many fields. See Methods and Properties for an Embedded Dossier for more information.

   Parameter Name	Data Type	Default Value	Available Values	Description	Required?
   props.dossierRenderingMode	String	consumption	["consumption", "authoring"]	The value is either "consumption" or "authoring". If it is "authoring" and the configuration feaure.dossier.authoring isn't set, or its value isn't true, then an error is returned.	No

   Example:

   Copy

   microstrategy.dossier.create({  
       ...
       "dossierRenderingMode": "authoring"
   })

   Response

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

   Copy

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

2. API for switching to authoring mode

   This API, similar to the resizeVisualization API, can ignore the restriction of the initial enabledRenderingModes.authoring parameter. This means when enabledRenderingModes.authoring is set to false, you cannot enter authoring mode via manual actions, but are able to via this API.

   Function

   Dossier.switchToMode(mode)

   Input Parameters

   Parameter Name	Description	Data Type	Available Values	Default Value
   mode	This is in the array ["authoring"]. Using API to return to consumption mode is not supported, so the input "consumption" returns an error.	String	["authoring"]	N/A

   Response

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

   Copy

   myDossier && myDossier.switchToMode("authoring").then(() => {
     ...
   }).catch(error => {
     ...
   })

   or

   Copy

   try {
     await myDossier.switchToMode("authoring");
   } catch(error) {
     ...
   }

   Since additional feedback information is not required, the callback parameters for the resolve case are not necessary.

   Similar to the behavior of the existing goToPage embedding API, the user's callback should be invoked when the editing page completes loading.

   Parameter Name	Data Type	Example	Comments
   error	Error object	new Error(“invalid operation!“)	See API Errors for more information.

3. Callback for monitoring when the dossier is saved or closed

   When the Save or Close button is clicked in authoring mode, an event is raised that notifies your application.

   Event Name

   Parameter Name	Trigger
   onDossierAuthoringSaved	When the dossier is saved in authoring mode.
   onDossierAuthoringClosed	When the dossier is closed in authoring mode.

   Callback Format

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

   Copy

   myDossier && myDossier.registerEventHandler('onDossierAuthoringSaved', function(){
     ...      // The handling logic receiving the save event
   });
   
   myDossier && myDossier.registerEventHandler('onDossierAuthoringClosed', function(){
     ...      // The handling logic receiving the close event
   });

4. API for hiding the Edit button

   Function

   microstrategy.create(props)

   Input Parameters

   An optional props.navigationBar.edit field has been added to the props object. The props parameter contains many fields. See Methods and Properties for an Embedded Dossier for more information.

   Parameter Name	Data Type	Default Value	Description	Required?
   props.navigationBar.edit	Boolean	false	Edit the navigation bar of the UI.	No

   Example:

   Copy

   microstrategy.dossier.create({  
       ...
       "navigationBar": {
           "edit": false
       }
   })

   If you do not enter a value for navigationBar, the dossier runs using the old behavior and the navigation bar is hidden.

   Response

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

   Copy

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

5. API for controlling the authoring UI

   This functionality has been added starting in MicroStrategy 2021 Update 4.

   Function

   microstrategy.create(props)

   Input Parameters

   Parameter Names	Data Type	Default Value	Description	Required?
   props.authoring.menubar.library.visible	Boolean	true	Show or hide corresponding Library home button in the authoring UI.	No
   props.authoring.toolbar.tableOfContents.visible props.authoring.toolbar.undo.visible props.authoring.toolbar.redo.visible props.authoring.toolbar.refresh.visible props.authoring.toolbar.pauseDataRetrieval.visible props.authoring.toolbar.reprompt.visible props.authoring.toolbar.dividerLeft.visible props.authoring.toolbar.addData.visible props.authoring.toolbar.addChapter.visible props.authoring.toolbar.addPage.visible props.authoring.toolbar.insertVisualization.visible props.authoring.toolbar.insertFilter.visible props.authoring.toolbar.insertText.visible props.authoring.toolbar.insertImage.visible props.authoring.toolbar.insertHtml.visible props.authoring.toolbar.insertSurvey.visible props.authoring.toolbar.insertShape.visible props.authoring.toolbar.insertPanelStack.visible props.authoring.toolbar.insertInfoWindow.visible props.authoring.toolbar.save.visible props.authoring.toolbar.dividerRight.visible props.authoring.toolbar.more.visible props.authoring.toolbar.freeformLayout.visible props.authoring.toolbar.nlp.visible props.authoring.toolbar.responsiveViewEditor.visible props.authoring.toolbar.responsivePreview.visible	Boolean	true	Show or hide corresponding buttons on the toolbar in the authoring UI.	No
   props.authoring.panelVisibility.contents props.authoring.panelVisibility.datasets props.authoring.panelVisibility.editor props.authoring.panelVisibility.filter props.authoring.panelVisibility.format props.authoring.panelVisibility.layers	Boolean	true	Show or hide corresponding authoring panels.	No

   The props parameter contains many fields. See Methods and Properties for an Embedded Dossier for more information.

   Example:

   Copy

   microstrategy.dossier.create({
       placeholder: placeholderDiv,
       url: http: //{host}:{port}/{Library}/app/{ProjectID}/{DossierID}, 
           authoring: {
               menubar: {
                   library: {
                       visible: false
                   }
               },
               toolbar: {
                   tableOfContents: {
                       visible: false
                   }
               },
               panelVisibility: {
                   contents: false
               }
           }
   })

   Response

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

   Copy

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

6. API for creating a new dossier for authoring

   This functionality has been added starting in MicroStrategy 2021 Update 4.

   Function

   microstrategy.create(props)

   Input Parameters

   Parameter Names	Data Type	Default Value	Description	Required?
   props.newDossier	Boolean	false	Use when creating a new dossier from scratch. When set to true, a new dossier instance is created from a blank dossier template. In this case, the instance, objectID, or url parameters don't have to and shouldn't be provided.	No

   The props parameter contains many fields. See Methods and Properties for an Embedded Dossier for more information.

   Example:

   Copy

   microstrategy.dossier.create({
       placeholder: placeholderDiv,
       newDossier: true,
       dossierRenderingMode: true
   })

   Response

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

   Copy

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

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.

microstrategy.dossier.create({
...
"authoring": {value}
})

microstrategy.dossier.create({
    authoring: {
        panelVisibility: {
            <panelKey>: {panelValue},
            ...
        }
    },
    instance: {
        mid: "F9D198674597EEDA4848F5962AC42A72",
        status: 1,
    },
    newDossier: {newInstanceValue},
    ...
})

microstrategy.dossier.create({
...
"dossierRenderingMode":{value}
})

microstrategy.dossier.create({
...
{unsupportedFieldsInAuthoringMode}: {value},
"dossierRenderingMode": "authoring"
})

myDossier.switchToMode(mode)

myDossier.{unsupportedFunctionName}