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
-
Change the microstrategy.dossier.create API to add new fields in its initialized parameter object in the following situations:
-
When entering authoring mode when displaying the page.
-
When hiding the Edit button when displaying the page in consumption mode.
-
-
Add the Dossier.switchToMode API to allow the switch from view mode to authoring mode.
-
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.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 withdossierRenderingMode = 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
andvisualizationAppearances
. These parameters are implementations of some embedding SDK APIs (for example, filter-related functions in the dossier class andchangeVisualizationSize
) 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
-
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 theprops
object in 2021 Update 3. Theprops
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 configurationfeaure.dossier.authoring
isn't set, or its value isn't true, then an error is returned.No Example:
Copymicrostrategy.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.Copyvar placeholderDiv = document.getElementById("dossierContainer");
var myDossier;
microstrategy.dossier.create({
...
}).then(function(dossier){
myDossier = dossier; ...
}); - API for switching to authoring mode
This API, similar to the
resizeVisualization
API, can ignore the restriction of the initialenabledRenderingModes.authoring
parameter. This means whenenabledRenderingModes.authoring
is set tofalse
, 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.
CopymyDossier && myDossier.switchToMode("authoring").then(() => {
...
}).catch(error => {
...
})or
Copytry {
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. - 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.CopymyDossier && myDossier.registerEventHandler('onDossierAuthoringSaved', function(){
... // The handling logic receiving the save event
});
myDossier && myDossier.registerEventHandler('onDossierAuthoringClosed', function(){
... // The handling logic receiving the close event
}); - API for hiding the Edit button
Function
microstrategy.create(props)
Input Parameters
An optional
props.navigationBar.edit
field has been added to theprops
object. Theprops
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:
Copymicrostrategy.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.Copyvar placeholderDiv = document.getElementById("dossierContainer");
var myDossier;
microstrategy.dossier.create({
...
}).then(function(dossier){
myDossier = dossier; ...
}); -
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.visibleBoolean 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.layersBoolean 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:
Copymicrostrategy.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.Copyvar placeholderDiv = document.getElementById("dossierContainer");
var myDossier;
microstrategy.dossier.create({
...
}).then(function(dossier) {
myDossier = dossier;...
}); -
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, theinstance
,objectID
, orurl
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:
Copymicrostrategy.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.Copyvar 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
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 |
Error when valid parameter for microstrategy.dossier.create: data.authoring.toolbar should be object |
||||
Copy
|
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 |
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
|
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 |
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
|
Unsupported case
|
Embedded SDK | The unsupported fields in the authoring mode include:
|
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
|
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
|
Unsupported case |
Web Dossier |
Unsupported API in authoring mode. |
The API ${APIName} isn't supported in the authoring mode! |