Version 2021

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.

Supported API Description
microstrategy.dossier.create

 

Creates or destroys the embedded dossier view.

 

microstrategy.dossier.destroy
Dossier.switchToMode The API added in this feature used in authoring mode.
Dossier.registerEventHandler

Adds an event handler.

Dossier.removeEventhandler

Removes an event handler.

Dossier.registerFilterUpdateHandler

 

 

 

Calls the same dossier functions in Web with Dossier.registerEventHandler so all could be used in authoring mode.

 

 

 

Dossier.registerPageSwitchHandler
Dossier.registerDossierInstanceIDChangeHandler
Dossier.registerGraphicsSelectEventHandlerToViz
Dossier.addCustomErrorHandler

 

 

 

Handles the error handlers.

 

 

 

Dossier.removeCustomErrorhandler
Dossier.addSessionErrorHandler
Dossier.removeSessionErrorhandler
Dossier.makeSureSessionAlive

Checks the session. If it is expired, you should refresh it.

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.

Field Name Description
instance

An existing instance injected to the embedding SDK that is used for pre-handlings, like an answer prompt.

filters Applies filters to the dossier instance in consumption mode.
visualizationAppearances Applies visualization appearance manipulations to the dossier instance in consumption mode.
visualizationSelectedElements

Applies visualization element selections to the dossier instance in consumption mode.

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 NameDescriptionData TypeAvailable 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 NameData TypeExampleComments
    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 NameTrigger
    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 NameData TypeDefault ValueDescriptionRequired?
    props.navigationBar.editBoolean

    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.

Related APIs Error Category Handling Module Error Case Error Message Error Handling
Copy
microstrategy.dossier.create({
...
"authoring": {value}
})

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

Invalid input

 

Embedded SDK

 

The authoring parameter has the wrong input type Error when valid parameter for microstrategy.dossier.create: data.authoring should be object or null Display the error message or an alert dialog

 

The authoring.toolbar has the wrong input type

Error when valid parameter for microstrategy.dossier.create: data.authoring.toolbar should be object

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

 

 

Invalid input

 

 

Embedded SDK

 

 

The {panelValue} has the wrong data type Error when valid parameter for microstrategy.dossier.create: data.authoring.panelVisibility.<panelKey> should be boolean Display the error message or an alert dialog(Existing behavior)

 

The {newInstanceValue} has the wrong data type

Error when valid parameter for microstrategy.dossier.create: data.newDossier should be boolean

There are inconsistent parameters with “newDossier"

You shouldn't input 'instance', 'objectID' or 'url' when newDossier is true

 

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

 

 

Embedded SDK

 

The dossierRenderingMode parameter has the wrong input type. Error when valid parameter for microstrategy.dossier.create: data.dossierRenderingMode should be string

 

Display the error message or an alert dialog (existing behavior).

The dossierRenderingMode parameter is neither “consumption“ nor “authoring“.

Error when valid parameter for microstrategy.dossier.create: data.dossierRenderingMode should match pattern "(^(consumption|authoring)$)"

Invalid input in the unsupported case

Web Dossier

 

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

You can not enter the authoring mode. The reason might be authoring is not enabled in this library server, or the object is not a dossier.

Caught by error handler.

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


Unsupported case

 

Embedded SDK The unsupported fields in the authoring mode include:
  • instance
  • filters
  • visualizationAppearances
  • visualizationSelectedElements
The fields ["instance", "filters", "visualizationAppearances", "visualizationSelectedElements"] are not allowed to be used when "dossierRenderingMode" is "authoring". Please remove these forbidden fields and try again.}’ Display the error message or an alert dialog (existing behavior).
Copy
myDossier.switchToMode(mode)

 

Unsupported case Web Dossier Dossier authoring isn’t allowed. The dossier authoring isn’t allowed for the current dossier and you couldn’t switch to the authoring mode.

 

Caught by the catch() of the promise object.

 

Copy
myDossier.{unsupportedFunctionName}
Unsupported case

Web Dossier

Unsupported API in authoring mode.

The API ${APIName} isn't supported in the authoring mode!