Embedding Contexts

This page is a reference to the EmbeddingContexts used in the `embed-dossier-mstr-react` library.

Type Definition

interface EmbeddingContexts {
  embedLibraryPage: (
    params: EmbedLibraryPageConfig
  ) => Promise<EmbedLibraryPage>
  embedDossierConsumptionPage: (
    params: EmbedDossierConsumptionPageConfig
  ) => Promise<EmbedDossierConsumptionPage>
  embedBotConsumptionPage: (
    params: EmbedBotConsumptionPageConfig
  ) => Promise<EmbedBotConsumptionPage>
  embedReportPage: (params: EmbedReportPageConfig) => Promise<EmbedReportPage>
  registerEventHandler: (event: EventTypes, handler: EventHandler) => void
  removeEventHandler: (event: EventTypes, handler: EventHandler) => void
  removeCustomErrorHandler: () => void
  removeSessionErrorHandler: () => void
  goToPage: (pageInfo: PageInfo) => Promise<{ redirect: boolean }>
  addCustomErrorHandler: (
    handler: (error: ErrorHandlerInterface) => void,
    showErrorPopup: boolean
  ) => void
  addSessionErrorHandler: (
    handler: (error: ErrorHandlerInterface) => void,
    showErrorPopup: boolean
  ) => void
}

Properties and Methods

embedLibraryPage

embedLibraryPage: (params: EmbedLibraryPageConfig) => Promise<EmbedLibraryPage>

Embeds a MicroStrategy Library page into your application. This enables users to browse and access all available MicroStrategy content, including dossiers, documents, and reports.

Parameters:

Returns:

  • Promise resolving to an EmbedLibraryPage object that provides methods for interacting with the embedded library page

Example:

const libraryPage =
  await window.microstrategy.embeddingContexts.embedLibraryPage({
    placeholder: document.getElementById("library-container"),
    serverUrl: "https://your-mstr-server/MicroStrategyLibrary",
    enableCustomAuthentication: true,
    customAuthenticationType:
      window.microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
    getLoginToken: async () => {
      // Get authentication token
      return "your-auth-token"
    },
  })

embedDossierConsumptionPage

embedDossierConsumptionPage: (params: EmbedDossierConsumptionPageConfig) =>
  Promise<EmbedDossierConsumptionPage>

Embeds a MicroStrategy dossier in consumption mode. This allows users to view and interact with dashboards but not edit them.

Parameters:

Returns:

Example:

const dossierPage =
  await window.microstrategy.embeddingContexts.embedDossierConsumptionPage({
    placeholder: document.getElementById("dossier-container"),
    serverUrl: "https://your-mstr-server/MicroStrategyLibrary",
    projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
    objectId: "54F3D26011D2896560009A8E67019608",
    enableCustomAuthentication: true,
    customAuthenticationType:
      window.microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
    getLoginToken: async () => {
      // Get authentication token
      return "your-auth-token"
    },
  })

embedBotConsumptionPage

embedBotConsumptionPage: (params: EmbedBotConsumptionPageConfig) =>
  Promise<EmbedBotConsumptionPage>

Embeds a MicroStrategy bot in consumption mode. Bots provide AI-powered analytics and natural language query capabilities.

Parameters:

Returns:

  • Promise resolving to an EmbedBotConsumptionPage object that provides methods for interacting with the embedded bot

Example:

const botPage =
  await window.microstrategy.embeddingContexts.embedBotConsumptionPage({
    placeholder: document.getElementById("bot-container"),
    serverUrl: "https://your-mstr-server/MicroStrategyLibrary",
    projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
    objectId: "D9AB3B1C44ED6F8CC0E4B39E7D4430F1",
    disableHyper: false,
    permissions: {
      allowClipboardWrite: true,
    },
  })

embedReportPage

embedReportPage: (params: EmbedReportPageConfig) => Promise<EmbedReportPage>

Embeds a MicroStrategy report. This allows users to view and interact with traditional MicroStrategy reports.

Parameters:

Returns:

  • Promise resolving to an EmbedReportPage object that provides methods for interacting with the embedded report

Example:

const reportPage = await window.microstrategy.embeddingContexts.embedReportPage(
  {
    placeholder: document.getElementById("report-container"),
    serverUrl: "https://your-mstr-server/MicroStrategyLibrary",
    projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
    objectId: "4C0D31B611D5C49EC0000C881FDA1A4F",
  }
)

registerEventHandler

registerEventHandler: (event: EventTypes, handler: EventHandler) => void

Registers an event handler for embedding context events.

Parameters:

  • event: EventTypes - The type of event to listen for
  • handler: EventHandler - The callback function to execute when the event occurs

Example:

window.microstrategy.embeddingContexts.registerEventHandler(
  "error",
  (error) => {
    console.error("Embedding context error:", error)
  }
)

removeEventHandler

removeEventHandler: (event: EventTypes, handler: EventHandler) => void

Removes a previously registered event handler.

Parameters:

  • event: EventTypes - The type of event the handler was registered for
  • handler: EventHandler - The original handler function to remove

Example:

const errorHandler = (error) => {
  console.error("Embedding context error:", error)
}

// Register handler
window.microstrategy.embeddingContexts.registerEventHandler(
  "error",
  errorHandler
)

// Later, remove the handler
window.microstrategy.embeddingContexts.removeEventHandler("error", errorHandler)

removeCustomErrorHandler

removeCustomErrorHandler: () => void

Removes any custom error handlers that were previously added.

Example:

window.microstrategy.embeddingContexts.removeCustomErrorHandler()

removeSessionErrorHandler

removeSessionErrorHandler: () => void

Removes any session error handlers that were previously added.

Example:

window.microstrategy.embeddingContexts.removeSessionErrorHandler()

goToPage

goToPage: (pageInfo: PageInfo) => Promise<{ redirect: boolean }>

Navigates to a specific page within the MicroStrategy application.

Parameters:

  • pageInfo: PageInfo - Information about the target page

Returns:

  • Promise resolving to an object with a redirect boolean property indicating if the navigation was successful

Example:

const result = await window.microstrategy.embeddingContexts.goToPage({
  pageName: "dossier",
  projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
  objectId: "54F3D26011D2896560009A8E67019608",
})

if (result.redirect) {
  console.log("Successfully navigated to the page")
}

addCustomErrorHandler

addCustomErrorHandler: (handler: (error: ErrorHandlerInterface) => void, showErrorPopup: boolean) => void

Adds a custom error handler for application errors.

Parameters:

  • handler: Function - The error handler callback that receives an ErrorHandlerInterface object
  • showErrorPopup: boolean - Whether to show the default error popup in addition to calling the custom handler

Example:

window.microstrategy.embeddingContexts.addCustomErrorHandler((error) => {
  console.error("Custom error handler:", error.message)
  // Take additional actions based on the error
}, false)

addSessionErrorHandler

addSessionErrorHandler: (handler: (error: ErrorHandlerInterface) => void, showErrorPopup: boolean) => void

Adds a session error handler specifically for authentication and session-related errors.

Parameters:

  • handler: Function - The error handler callback that receives an ErrorHandlerInterface object
  • showErrorPopup: boolean - Whether to show the default error popup in addition to calling the custom handler

Example:

window.microstrategy.embeddingContexts.addSessionErrorHandler((error) => {
  console.error("Session error:", error.message)
  if (error.code === "SESSION_EXPIRED") {
    // Refresh the session
    initiateReauthentication()
  }
}, false)

Usage with embed-dossier-mstr-react

The embed-dossier-mstr-react library provides React components and hooks that make it easier to work with these embedding contexts:

import {
  LibraryPageEmbed,
  BotConsumptionPage,
  BotConsumptionPageWithAuth,
  DashboardEmbed,
  DashboardEmbedWithAuth
} from "embed-dossier-mstr-react";

// Using the library page embed component
<LibraryPageEmbed
  serverUrlLibrary="https://your-mstr-server/MicroStrategyLibrary"
  config={{
    customUi: {
      headerEnabled: false
    }
  }}
  className="h-screen"
/>

// Using the bot consumption page with authentication
<BotConsumptionPageWithAuth
  serverUrlLibrary="https://your-mstr-server/MicroStrategyLibrary"
  projectId="B19DEDCC11D4E0EFC000EB9495D0F44F"
  objectId="D9AB3B1C44ED6F8CC0E4B39E7D4430F1"
  loginMode="standard"
  username="user"
  password="pass"
  config={{
    disableHyper: false
  }}
/>