Skip to content

Commit 130d10e

Browse files
Aran0011Yu, Ran
Aran0011
and
Yu, Ran
authored
Add the parallel rendering docus (#75)
Co-authored-by: Yu, Ran <ryu@microstrategy.com>
1 parent 62ee825 commit 130d10e

2 files changed

Lines changed: 324 additions & 0 deletions

File tree

‎docs/microstrategy-rest-api-samples/apply-filters-parallel-rendering-workflow.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
title: Apply Filters with Parallel Rendering for Initial Dashboard Rendering
3+
description: This workflow sample demonstrates how to enable Parallel Rendering for dashboard instances when applying filters before the initial render, using the MicroStrategy REST API.
4+
---
5+
6+
<Available since="2026 Update 2" />
7+
8+
**Parallel Rendering** (also referred to as **Incremental Rendering**) enables progressive rendering of multiple visualizations, enhancing load performance and the overall user experience. Users can enable this feature for a dashboard via the dashboard properties panel; however, it is only supported for initial dashboard execution. Any subsequent user manipulations will remove the Parallel Rendering flag from the dashboard instance.
9+
10+
This workflow sample demonstrates how to enable **Parallel Rendering** for dashboard instances in use cases where filters must be applied prior to rendering. It leverages **resolve-only** mode during instance creation and filter application, which allows filters to be applied safely before triggering Parallel Rendering—ensuring optimized load performance. When the `parallelRenderingAfterManipulation` parameter is set to `true`, the final render process runs with Parallel Rendering enabled, guaranteeing a streamlined, progressive loading experience for the end user.
11+
12+
## Workflow Scenarios
13+
14+
Two scenarios are supported, depending on your use case:
15+
16+
**Scenario 1: Apply filters during instance creation**
17+
Include the filters directly in the Create Instance request.
18+
19+
**Scenario 2: Apply filters after instance creation**
20+
This scenario involves two steps:
21+
22+
1. Create the instance (optionally with initial filters).
23+
1. Apply additional filters after the instance is created.
24+
25+
In both scenarios, you may observe the parallel rendering effect (faster load times and progressive visualization rendering) when opening the instance using the MicroStrategy [gotoPage API](https://microstrategy.github.io/embedding-sdk-docs/embedding-context/#gotopagepageinfo) or [create method](https://microstrategy.github.io/embedding-sdk-docs/add-functionality/methods-and-properties#microstrategydossiercreateprops).
26+
27+
> **Note:** For very simple dashboards or dashboards that execute quickly, the Parallel Rendering effect may not be noticeable, as the entire dashboard may render almost instantly.
28+
29+
:::info
30+
31+
Before executing the requests, replace all sample dashboard IDs, instance IDs, project IDs, auth tokens, and filters in the examples with your actual values.
32+
33+
You can obtain the authorization token using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
34+
35+
:::
36+
37+
## Scenario 1: Apply Filters During Instance Creation
38+
39+
This scenario applies filters directly when creating the dashboard instance, enabling parallel rendering in a single API call.
40+
41+
### POST /api/dossiers/\{dossierId\}/instances
42+
43+
Creates a new instance of a specific dashboard with filters applied during creation.
44+
45+
#### Request URL
46+
47+
```bash
48+
POST /api/dossiers/{dossierId}/instances
49+
```
50+
51+
#### Request Headers
52+
53+
| Name | Type | Description |
54+
| ------------------ | ------ | ----------------------------------------------------- |
55+
| `X-MSTR-AuthToken` | Header | Authorization token generated by POST /api/auth/login |
56+
| `X-MSTR-ProjectID` | Header | Project ID generated by GET /api/projects |
57+
58+
#### Sample Request Body
59+
60+
The key properties are:
61+
62+
- `resolveOnly`: Set to `true` to prepare the instance without full rendering
63+
- `enableParallelRendering`: Set to `false` during instance creation (parallel rendering is triggered later)
64+
- `filters`: Array of filter objects to apply to the dashboard
65+
- `applyFilterResolveOnly`: Set to `false` to fully execute the filter and trigger parallel rendering
66+
- `parallelRenderingAfterManipulation`: Set to `true` to enable parallel rendering after filters are applied
67+
68+
```json
69+
{
70+
"persistViewState": true,
71+
"resolveOnly": true,
72+
"ignoreMissingFilter": true,
73+
"enableParallelRendering": false,
74+
"filters": [
75+
{
76+
"key": "W2025834099",
77+
"name": "Budget Year",
78+
"selections": [
79+
{
80+
"id": "h2018;908C8901EC4ADFC06D11A19083E339F5",
81+
"name": "2018"
82+
},
83+
{
84+
"id": "h2020;908C8901EC4ADFC06D11A19083E339F5",
85+
"name": "2020"
86+
}
87+
]
88+
}
89+
],
90+
"applyFilterResolveOnly": false,
91+
"parallelRenderingAfterManipulation": true
92+
}
93+
```
94+
95+
#### Sample Curl Request
96+
97+
```bash
98+
curl -X 'POST' 'http://demo.microstrategy.com/MicroStrategyLibrary/api/dossiers/D61608A211E6C6E100000080EFC58627/instances' \
99+
-H 'accept: application/json' \
100+
-H 'X-MSTR-AuthToken: jhnatva9g0s47ittee8tnmkvd' \
101+
-H 'X-MSTR-ProjectID: EC70648611E7A2F962E90080EFD58751' \
102+
-H 'Content-Type: application/json' \
103+
-d '{
104+
"persistViewState": true,
105+
"resolveOnly": true,
106+
"ignoreMissingFilter": true,
107+
"enableParallelRendering": false,
108+
"filters": [
109+
{
110+
"key": "W2025834099",
111+
"name": "Budget Year",
112+
"selections": [
113+
{
114+
"id": "h2018;908C8901EC4ADFC06D11A19083E339F5",
115+
"name": "2018"
116+
},
117+
{
118+
"id": "h2020;908C8901EC4ADFC06D11A19083E339F5",
119+
"name": "2020"
120+
}
121+
]
122+
}
123+
],
124+
"applyFilterResolveOnly": false,
125+
"parallelRenderingAfterManipulation": true
126+
}'
127+
```
128+
129+
#### Sample Response
130+
131+
```json
132+
{
133+
"id": "00000000000000000000000000000000",
134+
"status": 1,
135+
"mid": "BB4335B5594A5E2AA38CD99100A676C6"
136+
}
137+
```
138+
139+
## Scenario 2: Apply Filters After Instance Creation
140+
141+
This scenario creates the instance first in resolve-only mode with `resolveOnly: true` (keep initial instance in **resolve-only** mode) and `applyFilterResolveOnly: true` (keeping instance after apply filters in **resolve-only** mode), then applies additional filters with parallel rendering enabled using a separate API call. This is useful when you need to prepare the instance quickly and apply multiple filters progressively before triggering the final parallel render.
142+
143+
### Step 1: Create Dashboard Instance
144+
145+
First, create a dashboard instance with `resolveOnly: true` and `enableParallelRendering: false` to quickly prepare the instance.
146+
147+
#### POST /api/dossiers/\{dossierId\}/instances
148+
149+
##### Request URL
150+
151+
```bash
152+
POST /api/dossiers/{dossierId}/instances
153+
```
154+
155+
##### Request Headers
156+
157+
| Name | Type | Description |
158+
| ------------------ | ------ | ----------------------------------------------------- |
159+
| `X-MSTR-AuthToken` | Header | Authorization token generated by POST /api/auth/login |
160+
| `X-MSTR-ProjectID` | Header | Project ID generated by GET /api/projects |
161+
162+
##### Sample Request Body
163+
164+
Key properties:
165+
166+
- `resolveOnly`: Set to `true` to prepare the instance without full rendering
167+
- `enableParallelRendering`: Set to `false` during instance creation (parallel rendering is triggered later)
168+
- `filters`: Array of filter objects to apply to the dashboard
169+
- `applyFilterResolveOnly`: Set to `true` to keep initial filters in resolve-only mode (not fully executed yet)
170+
- `parallelRenderingAfterManipulation`: Set to `false` for this initial step (will be enabled in Step 2)
171+
172+
```json
173+
{
174+
"persistViewState": true,
175+
"resolveOnly": true,
176+
"ignoreMissingFilter": true,
177+
"enableParallelRendering": false,
178+
"applyFilterResolveOnly": true,
179+
"parallelRenderingAfterManipulation": false,
180+
"filters": [
181+
{
182+
"key": "W2025834099",
183+
"name": "Budget Year",
184+
"selections": [
185+
{
186+
"id": "h2018;908C8901EC4ADFC06D11A19083E339F5",
187+
"name": "2018"
188+
}
189+
]
190+
}
191+
]
192+
}
193+
```
194+
195+
##### Sample Curl Request
196+
197+
```bash
198+
curl -X 'POST' 'http://demo.microstrategy.com/MicroStrategyLibrary/api/dossiers/D61608A211E6C6E100000080EFC58627/instances' \
199+
-H 'accept: application/json' \
200+
-H 'X-MSTR-AuthToken: jhnatva9g0s47ittee8tnmkvd' \
201+
-H 'X-MSTR-ProjectID: EC70648611E7A2F962E90080EFD58751' \
202+
-H 'Content-Type: application/json' \
203+
-d '{
204+
"persistViewState": true,
205+
"resolveOnly": true,
206+
"ignoreMissingFilter": true,
207+
"enableParallelRendering": false,
208+
"applyFilterResolveOnly": true,
209+
"parallelRenderingAfterManipulation": false,
210+
"filters": [
211+
{
212+
"key": "W2025834099",
213+
"name": "Budget Year",
214+
"selections": [
215+
{
216+
"id": "h2018;908C8901EC4ADFC06D11A19083E339F5",
217+
"name": "2018"
218+
}
219+
]
220+
}
221+
]
222+
}'
223+
```
224+
225+
##### Sample Response
226+
227+
```json
228+
{
229+
"id": "00000000000000000000000000000000",
230+
"status": 1,
231+
"mid": "BB4335B5594A5E2AA38CD99100A676C6"
232+
}
233+
```
234+
235+
Save the `mid` value from the response to use in Step 2.
236+
237+
### Step 2: Apply Additional Filters with Parallel Rendering
238+
239+
After creating the instance, apply additional filters using the PUT filters endpoint with `executionMode=DATA` and `parallelRenderingAfterManipulation=true`. This fully executes all filters (including those from Step 1) and enables parallel rendering for all subsequent operations on this instance.
240+
241+
Key query parameters:
242+
243+
- `executionMode=DATA`: Transitions the instance out of **resolve-only** mode and executes the filter to retrieve data
244+
- `parallelRenderingAfterManipulation=true`: Enables parallel rendering after filter applied
245+
246+
#### PUT /api/dossiers/\{dossierId\}/instances/\{instanceId\}/filters
247+
248+
##### Request URL
249+
250+
```bash
251+
PUT /api/dossiers/{dossierId}/instances/{instanceId}/filters?ignoreMissingFilter=false&executionMode=DATA&parallelRenderingAfterManipulation=true
252+
```
253+
254+
##### Query Parameters
255+
256+
| Name | Type | Description |
257+
| ------------------------------------ | ----- | ---------------------------------------------------------- |
258+
| `ignoreMissingFilter` | Query | Whether to ignore missing filters (false) |
259+
| `executionMode` | Query | Execution mode for the filter application (DATA) |
260+
| `parallelRenderingAfterManipulation` | Query | Enable parallel rendering after filter manipulation (true) |
261+
262+
##### Request Headers
263+
264+
| Name | Type | Description |
265+
| ------------------ | ------ | ----------------------------------------------------- |
266+
| `X-MSTR-AuthToken` | Header | Authorization token generated by POST /api/auth/login |
267+
| `X-MSTR-ProjectID` | Header | Project ID generated by GET /api/projects |
268+
269+
##### Sample Request Body
270+
271+
```json
272+
[
273+
{
274+
"key": "W2025834099",
275+
"name": "Budget Year",
276+
"selections": [
277+
{
278+
"id": "h2019;908C8901EC4ADFC06D11A19083E339F5",
279+
"name": "2019"
280+
},
281+
{
282+
"id": "h2020;908C8901EC4ADFC06D11A19083E339F5",
283+
"name": "2020"
284+
}
285+
]
286+
}
287+
]
288+
```
289+
290+
##### Sample Curl Request
291+
292+
```bash
293+
curl -X 'PUT' 'http://demo.microstrategy.com/MicroStrategyLibrary/api/dossiers/D61608A211E6C6E100000080EFC58627/instances/BB4335B5594A5E2AA38CD99100A676C6/filters?ignoreMissingFilter=false&executionMode=DATA&parallelRenderingAfterManipulation=true' \
294+
-H 'accept: application/json' \
295+
-H 'X-MSTR-AuthToken: jhnatva9g0s47ittee8tnmkvd' \
296+
-H 'X-MSTR-ProjectID: EC70648611E7A2F962E90080EFD58751' \
297+
-H 'Content-Type: application/json' \
298+
-d '[
299+
{
300+
"key": "W2025834099",
301+
"name": "Budget Year",
302+
"selections": [
303+
{
304+
"id": "h2019;908C8901EC4ADFC06D11A19083E339F5",
305+
"name": "2019"
306+
},
307+
{
308+
"id": "h2020;908C8901EC4ADFC06D11A19083E339F5",
309+
"name": "2020"
310+
}
311+
]
312+
}
313+
]'
314+
```
315+
316+
## Result
317+
318+
After completing either scenario, when you open a dashboard instance that takes a noticeable amount of time to load using the MicroStrategy [gotoPage API](https://microstrategy.github.io/embedding-sdk-docs/embedding-context/#gotopagepageinfo) or [create method](https://microstrategy.github.io/embedding-sdk-docs/add-functionality/methods-and-properties#microstrategydossiercreateprops), you may observe:
319+
320+
- **Faster initial load**: The dashboard frame renders more quickly, allowing users to see the layout immediately instead of a blank screen.
321+
- **Progressive rendering**: Visualizations appear as they complete, improving perceived performance.
322+
323+
> **Note:** For very simple dashboards or dashboards that execute quickly, the Parallel Rendering effect may not be noticeable, as the entire dashboard may render almost instantly.

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1383,6 +1383,7 @@ const sidebars = {
13831383
items: [
13841384
"microstrategy-rest-api-samples/create-reports-on-the-fly",
13851385
"microstrategy-rest-api-samples/react-user-manage-sample",
1386+
"microstrategy-rest-api-samples/apply-filters-parallel-rendering-workflow",
13861387
],
13871388
},
13881389
],

0 commit comments

Comments
 (0)