|
| 1 | +--- |
| 2 | +title: Create multiple instances for one dashboard |
| 3 | +description: The user can use Native Embedding SDK API to create multiple instances for one dashboard. |
| 4 | +--- |
| 5 | + |
| 6 | +<Available since="Strategy ONE December 2025"/> |
| 7 | + |
| 8 | +### One dashboard owns only one instance |
| 9 | + |
| 10 | +In the normal case, the Native Embedding SDK only creates one `MstrDossier` object for one dashboard object. That is, if you write code like this: |
| 11 | + |
| 12 | +```js |
| 13 | +const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ |
| 14 | + serverUrl: configs.serverUrl, |
| 15 | + getAuthToken, |
| 16 | +}); |
| 17 | +const mstrDossierA = await mstrEnvironment.loadDossier({ |
| 18 | + projectId: configs.projectId, |
| 19 | + objectId: configs.objectId, |
| 20 | +}); |
| 21 | +// mstrDossierB === mstrDossierA |
| 22 | +const mstrDossierB = await mstrEnvironment.loadDossier({ |
| 23 | + projectId: configs.projectId, |
| 24 | + objectId: configs.objectId, |
| 25 | +}); |
| 26 | +``` |
| 27 | + |
| 28 | +Then `mstrDossierB` will be the same as `mstrDossierA`. They are exactly the same object and share the same dashboard instance. For one dashboard instance, if it renders the visualizations from different pages, like: |
| 29 | + |
| 30 | +```js |
| 31 | +await mstrDossierA.refresh([ |
| 32 | + { |
| 33 | + key: "K52", // Page 1, viz 1 |
| 34 | + container: document.getElementById("container1"), |
| 35 | + }, |
| 36 | + { |
| 37 | + key: "W63", // Page 1, viz 2 |
| 38 | + container: document.getElementById("container2"), |
| 39 | + }, |
| 40 | + { |
| 41 | + key: "W64", // Page 2, viz 3 |
| 42 | + container: document.getElementById("container3"), |
| 43 | + }, |
| 44 | + { |
| 45 | + key: "R85", // Page 2, viz 4 |
| 46 | + container: document.getElementById("container4"), |
| 47 | + }, |
| 48 | +]); |
| 49 | +``` |
| 50 | + |
| 51 | +The dashboard will first fetch the page 1 data, render the visualization 1 and 2, and then fetch the page 2 data and render visualization 3 and 4. |
| 52 | + |
| 53 | +This brings a problem: If the user renders the visualizations from many different pages, the visualizations on different pages will render sequentially, which downgrades the performance. |
| 54 | + |
| 55 | +### One dashboard owns only multiple instances |
| 56 | + |
| 57 | +In Strategy ONE December 2025, we support one dossier to have multiple instances, which can render the visualizations from different pages in parallel, and accelerate the rendering speed. The point is, for each page, we can create a `MstrDossier` object that owns an independent dashboard instance, and these instances can be created and fetched data simultaneously. |
| 58 | + |
| 59 | +We need to use a new param `forceCreateNewInstance` in the [loadDossier()](./mstr-environment#the-load-dashboard-api) function to do this: |
| 60 | + |
| 61 | +```js |
| 62 | +const environment = await microstrategy.embeddingComponent.environments.create({ |
| 63 | + serverUrl, |
| 64 | + getAuthToken, |
| 65 | +}); |
| 66 | + |
| 67 | +async function refreshDossier(vizAndContainers) { |
| 68 | + const mstrDossier = await environment.loadDossier( |
| 69 | + { |
| 70 | + projectId, |
| 71 | + objectId, |
| 72 | + }, |
| 73 | + { |
| 74 | + forceCreateNewInstance: true, |
| 75 | + } |
| 76 | + ); |
| 77 | + await mstrDossier.refresh(vizAndContainers); |
| 78 | + return mstrDossier; |
| 79 | +} |
| 80 | + |
| 81 | +// Here mstrDossierA !== mstrDossierB |
| 82 | +const [mstrDossierA, mstrDossierB] = await Promise.all([ |
| 83 | + refreshDossier([ |
| 84 | + { |
| 85 | + key: "K52", // Page 1, viz 1 |
| 86 | + container: document.getElementById("container1"), |
| 87 | + }, |
| 88 | + { |
| 89 | + key: "W63", // Page 1, viz 2 |
| 90 | + container: document.getElementById("container2"), |
| 91 | + }, |
| 92 | + ]), |
| 93 | + refreshDossier([ |
| 94 | + { |
| 95 | + key: "W64", // Page 2, viz 1 |
| 96 | + container: document.getElementById("container3"), |
| 97 | + }, |
| 98 | + { |
| 99 | + key: "R85", // Page 2, viz 2 |
| 100 | + container: document.getElementById("container4"), |
| 101 | + }, |
| 102 | + ]), |
| 103 | +]); |
| 104 | +``` |
| 105 | + |
| 106 | +Here `mstrDossierA !== mstrDossierB`. The 2 `refreshDossier()` functions can be executed in parallel, which improves the rendering speed. |
| 107 | + |
| 108 | +### Change the working set limit |
| 109 | + |
| 110 | +On the Strategy iServer, the dashboard instance count limit for each user session is 10 by default. So if the embedding SDK user creates too many dashboard instances on a web page, the former instances might be expired or deleted. |
| 111 | + |
| 112 | +To solve this problem, the user can change the working set limit to a larger number. This could be done by assigning this limit by `workingSet` parameter in the [login API](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin) like: |
| 113 | + |
| 114 | +```js |
| 115 | +const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ |
| 116 | + serverUrl: configs.serverUrl, |
| 117 | + getAuthToken: () => { |
| 118 | + const options = { |
| 119 | + method: "POST", |
| 120 | + credentials: "include", |
| 121 | + mode: "cors", |
| 122 | + headers: { "content-type": "application/json" }, |
| 123 | + body: JSON.stringify({ |
| 124 | + loginMode: 1, |
| 125 | + username: "XXX", |
| 126 | + password: "YYY", |
| 127 | + // Enlarge the working set limit |
| 128 | + workingSet: 50, |
| 129 | + }), |
| 130 | + }; |
| 131 | + return fetch(`${configs.serverUrl}/api/auth/login`, options) |
| 132 | + .then((response) => { |
| 133 | + if (response.ok) { |
| 134 | + console.log("A new standard login session has been created successfully, logging in"); |
| 135 | + return response.headers.get("x-mstr-authtoken"); |
| 136 | + } |
| 137 | + return response.json().then((json) => console.log(json)); |
| 138 | + }) |
| 139 | + .catch((error) => console.error("Failed Standard Login with error:", error)); |
| 140 | + }, |
| 141 | +}); |
| 142 | +``` |
| 143 | + |
| 144 | +For the other type of authentication methods, like OIDC, you can set the `workingSet` number in the URL query parameter. |
| 145 | + |
| 146 | +### Verify whether the working set limit change succeeds |
| 147 | + |
| 148 | +If you want to check whether your working set limit change is successful, you can open the dev tool and check the GET /api/sessions REST API result: |
| 149 | + |
| 150 | +If the `workingSet` number in the REST API response is the same as the number you set, you setting works in the current session. |
0 commit comments