@mohsinonxrm/pptb-dataverse-request-studio 1.1.2 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,390 +1,390 @@
1
- # Dataverse Request Studio for Power Platform ToolBox
2
-
3
- A metadata-driven studio for composing, previewing, and executing Microsoft
4
- Dataverse Web API requests — covering OData reads, record writes, table
5
- associations, bound and unbound action/function invocation, on-demand workflows,
6
- and file / image / attachment operations.
7
-
8
- Built for [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) with
9
- React 18, Fluent UI v9, TypeScript, and live Dataverse metadata integration.
10
-
11
- ![Version](https://img.shields.io/badge/version-1.0.0-blue)
12
- ![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)
13
- ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)
14
- ![Fluent UI](https://img.shields.io/badge/Fluent%20UI-v9-0078D4?logo=microsoft)
15
- ![PPTB Types](https://img.shields.io/badge/%40pptb%2Ftypes-1.2.1-orange)
16
- ![License](https://img.shields.io/badge/license-AGPL--3.0--only-green)
17
-
18
- ---
19
-
20
- ## ✨ Features
21
-
22
- DRS ships with **17 request modes** organized into 5 functional groups. Every
23
- mode is metadata-driven, generates the correct OData / Web API shape, and
24
- emits ready-to-copy code in five languages (xrm.WebApi single + batch, fetch,
25
- curl, PowerShell).
26
-
27
- ### 📖 Read group
28
-
29
- - **Retrieve Multiple** — full OData query composer with `$select`, `$filter`,
30
- `$orderby`, `$expand`, `$top`, `$skip`, `$count`, `$apply` (groupby /
31
- aggregate), and a virtualized results grid with infinite scroll via
32
- `@odata.nextLink`.
33
- - **Retrieve Single** — by primary key OR by alternate key (composite
34
- alternate keys supported).
35
- - **Retrieve NextLink** — paste a `@odata.nextLink` URL to continue paging
36
- any query.
37
- - **Predefined Query** — execute saved-query (`?savedQuery=<id>`) and
38
- user-query (`?userQuery=<id>`) URLs against an entity set; layout-aware
39
- results grid that matches the source view's column order.
40
-
41
- ### ✏️ Write group
42
-
43
- - **Create Record** — `POST /<set>` with metadata-driven field-set editor.
44
- Required-field guard with red `req` badges, `Prefer: return=representation`
45
- toggle, optional `$select` return list, `MSCRM.*` bypass-header family.
46
- - **Update Record** — `PATCH /<set>(<id>)` multi-field OR
47
- `PUT /<set>(<id>)/<col>` single-column. Diff view (before → after) with
48
- per-row drill-down to switch to PUT mode.
49
- - **Upsert Record** — full upsert / create-only / update-only / etag-guarded
50
- variants. By GUID OR alternate key.
51
- - **Delete Record** — `DELETE /<set>(<id>)` with a typed-confirmation safety
52
- affordance + cascade-impact preview. Single-property delete via
53
- `DELETE /<set>(<id>)/<col>` also supported.
54
- - **Merge Records** — `POST /Merge` for `account` / `contact` / `incident`
55
- with target + subordinate record cards, field-override matrix, and
56
- PerformParentingChecks / SuppressDuplicateDetection settings.
57
-
58
- ### 🔗 Relate group
59
-
60
- - **Associate** — links related records via `POST /<set>(<id>)/<nav>/$ref`
61
- for collection-valued navs, or `PATCH @odata.bind` for single-valued.
62
- Cardinality detected from metadata; verb auto-flips with the picker.
63
- Polymorphic lookups (Customer / Owner / `regardingobjectid`) fully
64
- supported with target-disambiguated nav properties.
65
- - **Disassociate** — `DELETE /$ref` for collection-valued, `PATCH @odata.bind: null`
66
- for single-valued. Same polymorphism story.
67
-
68
- ### ⚡ Execute group
69
-
70
- - **Execute Action** — OOB / Custom API / Custom Action invocation via
71
- bound `POST /<set>(<id>)/Microsoft.Dynamics.CRM.<Action>` OR unbound
72
- `POST /<Action>`. CSDL-driven parameter form with type-aware controls:
73
- required-first UX, Form ↔ JSON toggle, EntityReference / EntityCollection
74
- / Edm primitives / Enum / Status-code OptionSet enrichment.
75
- - **Execute Function** — OData function calls with parameter aliasing
76
- (`?@p1=...`) vs inline literal toggle. CSDL-driven param form with the
77
- same type-aware controls as actions.
78
- - **Execute Workflow** — runs on-demand workflows via
79
- `POST /workflows(<id>)/Microsoft.Dynamics.CRM.ExecuteWorkflow` with the
80
- bound record id. Live picker over activated, on-demand process workflows
81
- (`statecode eq 1 and type eq 1 and ondemand eq true and category eq 0`).
82
-
83
- ### 💾 Binary group
84
-
85
- - **Manage File Data** — File-column upload / download / delete with three
86
- upload paths (single-request PATCH, chunked PATCH with session token,
87
- `InitializeFileBlocksUpload` / `UploadBlock` / `CommitFileBlocksUpload`
88
- messages), four download paths (single GET `/$value`, ranged GET with
89
- `Range`, message-based block download, `GetFileSasUrl` function), and the
90
- `DeleteFile` message + DELETE-on-property alternatives.
91
- - **Manage Image Data** — Image columns with thumbnail vs full-size
92
- download (`?size=full`), `CanStoreFullImage` awareness, and pointers to
93
- the file-column path for full-size uploads.
94
- - **Manage Attachment / Note** — `activitymimeattachment.body` and
95
- `annotation.documentbody`. Inline base 64 OR
96
- `Initialize{Attachment|Annotation}BlocksUpload` /
97
- `Commit{Attachment|Annotation}BlocksUpload` messages. Single-request
98
- GET `/$value` OR `Initialize{...}BlocksDownload` / `DownloadBlock` for
99
- download.
100
-
101
- ### 🔍 Cross-cutting capabilities
102
-
103
- - **Live metadata** — Tables, columns, relationships, alternate keys, action
104
- / function CSDL all fetched lazily from the host's `dataverseAPI`. Per-org
105
- TTL cache with in-flight promise dedup. Type-specific column properties
106
- (Targets, OptionSet, MaxLength, MinValue/MaxValue, Format) loaded on-demand
107
- by the editor that needs them.
108
- - **Antipattern advisories** — Surfaces real-time guidance per the
109
- [Microsoft query-antipatterns doc](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/query-antipatterns):
110
- `FilteringOnCalculatedColumns`, `LargeAmountOfLogicalAttributes`, large-text
111
- `contains`, leading-wildcard rewrites — all flagged inline AND aggregated
112
- into an Advisory drawer in the URL bar.
113
- - **Polymorphic lookup support** — Customer, Owner, and multi-target lookups
114
- (`regardingobjectid`) emit the correct target-disambiguated
115
- `<navName>@odata.bind` binding shape automatically.
116
- - **Code generators** — Every mode emits the same request as
117
- `Xrm.WebApi.online.execute` (single + `executeMultiple` batch),
118
- `fetch`, `curl`, and PowerShell `Invoke-RestMethod` snippets. Multi-request
119
- pipelines (chunked uploads, message-based binary ops) render as full
120
- ordered sequences.
121
- - **Saved-request library** — Per-org localStorage persistence with
122
- auto-suggested names (`account · 3 sel · 2 flt · 2026-05-23`),
123
- rename / delete / overwrite, dirty-state detection, and cross-tab sync.
124
- - **PPTB host integration** — `isEmbedded()`-aware UI: theme sync,
125
- environment-aware URLs, header pass-through, host-stripped header
126
- advisories. Header / theme controls hide when the host owns them.
127
-
128
- ---
129
-
130
- ## 🖼️ Interface overview
131
-
132
- ```
133
- ┌─────────────────────────────────────────────────────────────────────────┐
134
- │ [Request Type ▼] [Group · Method] [⚙ Settings] [Theme] │
135
- ├──────────────────────────┬──────────────────────────────────────────────┤
136
- │ │ [Builder] [Code] [Results] │
137
- │ Sidebar ├──────────────────────────────────────────────┤
138
- │ │ │
139
- │ 📋 Target │ Active editor pane │
140
- │ account │ │
141
- │ 📊 $select 3 sel │ ┌────────────────────────────────────────┐ │
142
- │ 🔍 $filter 2 flt │ │ (clause editor — varies per mode) │ │
143
- │ 🔁 $orderby 1 sort│ │ │ │
144
- │ 🔗 $expand 1 exp │ │ • Field-set editor (writes) │ │
145
- │ 📃 $top │ │ • Filter tree (reads) │ │
146
- │ ⚙ Prefer │ │ • Action param form (executes) │ │
147
- │ 📥 Headers 1 act │ │ • Binary pipeline (file/image) │ │
148
- │ │ └────────────────────────────────────────┘ │
149
- │ ⏱ Recent runs │ │
150
- │ 200 · 142ms · 32B │ │
151
- │ 200 · 89ms │ │
152
- │ │ │
153
- ├──────────────────────────┴──────────────────────────────────────────────┤
154
- │ GET /accounts?$select=name,… 0.4 KB ⚠ 2 advisories │
155
- │ [▶ Execute] │
156
- └─────────────────────────────────────────────────────────────────────────┘
157
- ```
158
-
159
- ---
160
-
161
- ## 🚀 Getting started
162
-
163
- ### Prerequisites
164
-
165
- - [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) (for embedded use)
166
- - A connection to a Dataverse environment
167
- - For local development: **Node.js ≥ 20.19** and **npm**
168
-
169
- ### Installation
170
-
171
- Dataverse Request Studio is available as a tool in Power Platform ToolBox.
172
- Install it from the tool gallery or load it as a custom tool.
173
-
174
- ---
175
-
176
- ## 🛠️ Development
177
-
178
- ### Setup
179
-
180
- ```bash
181
- git clone https://github.com/mohsinonxrm/pptb-mxrm-dataverse-request-studio.git
182
- cd pptb-mxrm-dataverse-request-studio
183
- npm install
184
- ```
185
-
186
- ### Common scripts
187
-
188
- ```bash
189
- # Vite dev server (standalone, no PPTB host)
190
- npm run dev
191
-
192
- # TypeScript-only check (fast)
193
- npm run typecheck
194
-
195
- # Production build
196
- npm run build
197
-
198
- # Preview the production build locally
199
- npm run preview
200
-
201
- # Validate manifest against PPTB registry rules
202
- npm run validate
203
-
204
- # Pre-publish: validate → build → shrinkwrap
205
- npm run finalize-package
206
- ```
207
-
208
- ### Standalone vs PPTB-embedded
209
-
210
- DRS runs in two modes:
211
-
212
- - **Standalone** (`npm run dev`) — opens in a regular browser tab. Useful
213
- for UI iteration. Execute will return `501 Not Implemented` for any
214
- operation because the host bridge isn't present; you can still build
215
- requests, preview URLs, and use the Code tab.
216
- - **Embedded in PPTB** — loads inside the PPTB iframe. The host injects
217
- `window.dataverseAPI` (typed) and `window.toolboxAPI`. Execute runs
218
- against the active Dataverse connection.
219
-
220
- See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for branch conventions,
221
- commit style, code style, and PR guidance.
222
-
223
- ---
224
-
225
- ## 📦 Tech stack
226
-
227
- | Technology | Version | Purpose |
228
- |---|---|---|
229
- | **React** | 18.3 | UI framework |
230
- | **TypeScript** | 5.9 | Strict mode, discriminated unions |
231
- | **Vite** | 7 | Build tooling + HMR |
232
- | **Fluent UI v9** | 9.73 | Microsoft design system (Combobox, DataGrid, Tree, Drawer, Tabs, etc.) |
233
- | **Monaco Editor** | 0.54 | JSON / code editor for body authoring and Code tab |
234
- | **@fluentui-contrib/react-data-grid-react-window** | 1.4 | Virtualized results grid |
235
- | **@dnd-kit** | 6.3 | Drag-reordering for filter / orderby / select clauses |
236
- | **@pptb/types** | 1.2.1 | Power Platform ToolBox host API types |
237
-
238
- ---
239
-
240
- ## 📁 Project layout
241
-
242
- ```
243
- src/
244
- App.tsx — root, ThemedApp, Frame, mode router
245
- main.tsx — Vite entry point
246
-
247
- modes/ — one file per request mode (17 modes)
248
- RetrieveMultipleMode.tsx
249
- RetrieveSingleMode.tsx
250
- RetrieveNextLinkMode.tsx
251
- PredefinedQueryMode.tsx
252
- CreateMode.tsx / UpdateMode.tsx / UpsertMode.tsx / DeleteMode.tsx
253
- MergeMode.tsx
254
- AssociateMode.tsx / DisassociateMode.tsx
255
- ExecuteActionMode.tsx / ExecuteFunctionMode.tsx / ExecuteWorkflowMode.tsx
256
- ManageFileMode.tsx / ManageImageMode.tsx / ManageAttachmentMode.tsx
257
-
258
- editors/ — clause editors shared across modes
259
- filter/ — FilterEditor + value inputs + operator catalog
260
- FieldSetEditor.tsx — metadata-driven write-side form
261
- SelectEditor.tsx, OrderbyEditor.tsx, ExpandEditor.tsx, ApplyEditor.tsx
262
- ActionParamForm.tsx — CSDL-driven action / function params
263
- BinarySourceCard.tsx, BinaryPipelineCard.tsx, BinaryColumnPickers.tsx
264
- HeadersEditor.tsx, BypassEditor.tsx
265
- ActionPicker.tsx, RecordPicker.tsx, EntityListPicker.tsx
266
- ...
267
-
268
- engine/ — URL / body construction + code generation
269
- urlBuilder.ts — central URL builder for every mode
270
- executeBuilders.ts — action / function / workflow body builders
271
- binaryBuilders.ts — file / image / attachment pipelines
272
- codeGenerators.ts — xrm, xrm-batch, fetch, curl, PowerShell
273
- runtime.ts — single dispatch point for execute
274
- dataverseExecutor.ts — live executor over the host's dataverseAPI
275
- odataParser.ts — round-trips OData URL strings ↔ state
276
-
277
- host/ — PPTB bridge + metadata loaders
278
- pptbBridge.ts — typed wrapper over window.dataverseAPI
279
- metadataProvider.ts — entity / attribute / relationship loaders
280
- csdlProvider.ts — $metadata XML parsing + action / function index
281
- cache.ts — singleton TTL cache with in-flight dedup
282
- useLiveMetadata.ts, useColumnDetail.ts, useScopedEntities.ts, …
283
-
284
- primitives/ — small reusable UI bits
285
- Sidebar.tsx, ClauseTreeItem.tsx, SectionHeader.tsx, ModeCard.tsx
286
- StatusPill.tsx, MethodPill.tsx, AdvisoryDrawer.tsx, advisories.ts
287
- NavPathColumnPicker.tsx — N:1 drill-down column picker for filter / apply
288
- KvGrid.tsx, Sortable.tsx, SegmentedToggle.tsx, …
289
-
290
- shell/ — frame / header / URL bar / tabs / drawers
291
- Frame.tsx, FrameHeader.tsx, ModeShell.tsx
292
- UrlBar.tsx, MainTabs.tsx, SettingsDrawer.tsx
293
-
294
- state/ — per-mode state shapes + persistence
295
- readState.ts, writeState.ts, relateState.ts, executeState.ts, binaryState.ts
296
- savedRequests.ts — localStorage persistence (per-org scope)
297
- SaveContext.tsx — cross-mode save/load context
298
- displaySettings.ts — display preferences
299
-
300
- registry/ — request-type catalogue
301
- requestTypes.ts — 17 request types grouped into 5 groups
302
-
303
- views/ — output panes
304
- CodeView.tsx — Code tab: xrm/xrm-batch/fetch/curl/powershell
305
- ResultsView.tsx — tabs (Detail/Grid/JSON/Headers) + error state
306
- results/ — grid + cell renderers + flattening
307
- detail/ — record detail card
308
-
309
- theme/ — Fluent theme + studio-owned brand vars
310
- ```
311
-
312
- ---
313
-
314
- ## 📋 Web API coverage
315
-
316
- | Operation | Status |
317
- |---|---|
318
- | Retrieve Multiple (full OData) | ✅ |
319
- | Retrieve Single (by GUID / alt key) | ✅ |
320
- | `@odata.nextLink` paging | ✅ |
321
- | Predefined / user queries | ✅ |
322
- | `$apply` (groupby / aggregate) | ✅ |
323
- | Lambda filter (`any` / `all`) | ✅ |
324
- | `$expand` (single + collection, nested) | ✅ |
325
- | Polymorphic lookups (Customer, Owner, regardingobjectid) | ✅ |
326
- | Create / Update / Upsert / Delete | ✅ |
327
- | `Prefer: return=representation` | ✅ |
328
- | Optimistic concurrency (`If-Match` ETag) | ✅ |
329
- | `MSCRM.*` bypass family (custom plug-ins, flows, async) | ✅ |
330
- | Single-property PUT / DELETE | ✅ |
331
- | Alternate-key upsert | ✅ |
332
- | Associate / Disassociate (collection + single-valued) | ✅ |
333
- | Merge (account / contact / incident) | ✅ |
334
- | Execute Action (OOB / Custom API / Custom Action) | ✅ |
335
- | Execute Function | ✅ |
336
- | Execute Workflow | ✅ |
337
- | File column (upload / download / delete) | ✅ |
338
- | Image column (thumbnail / full-size) | ✅ |
339
- | Attachment / Note (inline + message-based) | ✅ |
340
- | `$batch` envelope composer | ⏳ (see roadmap) |
341
- | `CreateMultiple` / `UpdateMultiple` / `DeleteMultiple` | ⏳ |
342
- | `BulkDelete` async job | ⏳ |
343
- | `ExecuteMultiple` envelope | ⏳ |
344
-
345
- ---
346
-
347
- ## 🤝 Contributing
348
-
349
- See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for branch conventions,
350
- commit style, code style, repo layout, and PR guidance.
351
-
352
- ---
353
-
354
- ## 📋 Roadmap
355
-
356
- - `$batch` envelope composer mode
357
- - Bulk-write modes (`CreateMultiple`, `UpdateMultiple`, `DeleteMultiple`)
358
- - `BulkDelete` async-job composer
359
- - `ExecuteMultiple` request envelope
360
- - Recent-runs click-to-reload
361
- - WriteResultCard "Retrieve this record" cross-mode jump
362
- - EntitySpecific param — reference vs new-instance toggle
363
- - Workflow input parameters (parse XAML `InArgument`)
364
- - Predefined Query — apply to related collection
365
- - CSV / JSON export from results grid
366
- - Column resize with persisted widths
367
- - Smoke-test suite covering URL builders + code generators
368
-
369
- ---
370
-
371
- ## 📄 License
372
-
373
- Licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0-only).
374
- See [LICENSE](LICENSE) for details.
375
-
376
- ---
377
-
378
- ## 🙏 Acknowledgments
379
-
380
- - [Dataverse REST Builder](https://github.com/GuidoPreite/DRB) - Original inspiration.
381
- - [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) — host
382
- platform for the desktop / web app where DRS runs.
383
- - [FetchXML Studio](https://github.com/mohsinonxrm/pptb-mxrm-fetchxml-studio) — sibling tool that pioneered many of the patterns
384
- reused here (metadata cache, scope settings, results grid).
385
- - [Fluent UI](https://react.fluentui.dev/) — UI component library.
386
- - [Monaco Editor](https://microsoft.github.io/monaco-editor/) — VS Code's editor core.
387
-
388
- ---
389
-
390
- Built with ❤️ for the Power Platform community.
1
+ # Dataverse Request Studio for Power Platform ToolBox
2
+
3
+ A metadata-driven studio for composing, previewing, and executing Microsoft
4
+ Dataverse Web API requests — covering OData reads, record writes, table
5
+ associations, bound and unbound action/function invocation, on-demand workflows,
6
+ and file / image / attachment operations.
7
+
8
+ Built for [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) with
9
+ React 18, Fluent UI v9, TypeScript, and live Dataverse metadata integration.
10
+
11
+ [![npm](https://img.shields.io/npm/v/@mohsinonxrm/pptb-dataverse-request-studio?label=npm)](https://www.npmjs.com/package/@mohsinonxrm/pptb-dataverse-request-studio)
12
+ ![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)
13
+ ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)
14
+ ![Fluent UI](https://img.shields.io/badge/Fluent%20UI-v9-0078D4?logo=microsoft)
15
+ ![PPTB Types](https://img.shields.io/badge/%40pptb%2Ftypes-1.2.1-orange)
16
+ ![License](https://img.shields.io/badge/license-AGPL--3.0--only-green)
17
+
18
+ ---
19
+
20
+ ## ✨ Features
21
+
22
+ DRS ships with **17 request modes** organized into 5 functional groups. Every
23
+ mode is metadata-driven, generates the correct OData / Web API shape, and
24
+ emits ready-to-copy code in five languages (xrm.WebApi single + batch, fetch,
25
+ curl, PowerShell).
26
+
27
+ ### 📖 Read group
28
+
29
+ - **Retrieve Multiple** — full OData query composer with `$select`, `$filter`,
30
+ `$orderby`, `$expand`, `$top`, `$skip`, `$count`, `$apply` (groupby /
31
+ aggregate), and a virtualized results grid with infinite scroll via
32
+ `@odata.nextLink`.
33
+ - **Retrieve Single** — by primary key OR by alternate key (composite
34
+ alternate keys supported).
35
+ - **Retrieve NextLink** — paste a `@odata.nextLink` URL to continue paging
36
+ any query.
37
+ - **Predefined Query** — execute saved-query (`?savedQuery=<id>`) and
38
+ user-query (`?userQuery=<id>`) URLs against an entity set; layout-aware
39
+ results grid that matches the source view's column order.
40
+
41
+ ### ✏️ Write group
42
+
43
+ - **Create Record** — `POST /<set>` with metadata-driven field-set editor.
44
+ Required-field guard with red `req` badges, `Prefer: return=representation`
45
+ toggle, optional `$select` return list, `MSCRM.*` bypass-header family.
46
+ - **Update Record** — `PATCH /<set>(<id>)` multi-field OR
47
+ `PUT /<set>(<id>)/<col>` single-column. Diff view (before → after) with
48
+ per-row drill-down to switch to PUT mode.
49
+ - **Upsert Record** — full upsert / create-only / update-only / etag-guarded
50
+ variants. By GUID OR alternate key.
51
+ - **Delete Record** — `DELETE /<set>(<id>)` with a typed-confirmation safety
52
+ affordance + cascade-impact preview. Single-property delete via
53
+ `DELETE /<set>(<id>)/<col>` also supported.
54
+ - **Merge Records** — `POST /Merge` for `account` / `contact` / `incident`
55
+ with target + subordinate record cards, field-override matrix, and
56
+ PerformParentingChecks / SuppressDuplicateDetection settings.
57
+
58
+ ### 🔗 Relate group
59
+
60
+ - **Associate** — links related records via `POST /<set>(<id>)/<nav>/$ref`
61
+ for collection-valued navs, or `PATCH @odata.bind` for single-valued.
62
+ Cardinality detected from metadata; verb auto-flips with the picker.
63
+ Polymorphic lookups (Customer / Owner / `regardingobjectid`) fully
64
+ supported with target-disambiguated nav properties.
65
+ - **Disassociate** — `DELETE /$ref` for collection-valued, `PATCH @odata.bind: null`
66
+ for single-valued. Same polymorphism story.
67
+
68
+ ### ⚡ Execute group
69
+
70
+ - **Execute Action** — OOB / Custom API / Custom Action invocation via
71
+ bound `POST /<set>(<id>)/Microsoft.Dynamics.CRM.<Action>` OR unbound
72
+ `POST /<Action>`. CSDL-driven parameter form with type-aware controls:
73
+ required-first UX, Form ↔ JSON toggle, EntityReference / EntityCollection
74
+ / Edm primitives / Enum / Status-code OptionSet enrichment.
75
+ - **Execute Function** — OData function calls with parameter aliasing
76
+ (`?@p1=...`) vs inline literal toggle. CSDL-driven param form with the
77
+ same type-aware controls as actions.
78
+ - **Execute Workflow** — runs on-demand workflows via
79
+ `POST /workflows(<id>)/Microsoft.Dynamics.CRM.ExecuteWorkflow` with the
80
+ bound record id. Live picker over activated, on-demand process workflows
81
+ (`statecode eq 1 and type eq 1 and ondemand eq true and category eq 0`).
82
+
83
+ ### 💾 Binary group
84
+
85
+ - **Manage File Data** — File-column upload / download / delete with three
86
+ upload paths (single-request PATCH, chunked PATCH with session token,
87
+ `InitializeFileBlocksUpload` / `UploadBlock` / `CommitFileBlocksUpload`
88
+ messages), four download paths (single GET `/$value`, ranged GET with
89
+ `Range`, message-based block download, `GetFileSasUrl` function), and the
90
+ `DeleteFile` message + DELETE-on-property alternatives.
91
+ - **Manage Image Data** — Image columns with thumbnail vs full-size
92
+ download (`?size=full`), `CanStoreFullImage` awareness, and pointers to
93
+ the file-column path for full-size uploads.
94
+ - **Manage Attachment / Note** — `activitymimeattachment.body` and
95
+ `annotation.documentbody`. Inline base 64 OR
96
+ `Initialize{Attachment|Annotation}BlocksUpload` /
97
+ `Commit{Attachment|Annotation}BlocksUpload` messages. Single-request
98
+ GET `/$value` OR `Initialize{...}BlocksDownload` / `DownloadBlock` for
99
+ download.
100
+
101
+ ### 🔍 Cross-cutting capabilities
102
+
103
+ - **Live metadata** — Tables, columns, relationships, alternate keys, action
104
+ / function CSDL all fetched lazily from the host's `dataverseAPI`. Per-org
105
+ TTL cache with in-flight promise dedup. Type-specific column properties
106
+ (Targets, OptionSet, MaxLength, MinValue/MaxValue, Format) loaded on-demand
107
+ by the editor that needs them.
108
+ - **Antipattern advisories** — Surfaces real-time guidance per the
109
+ [Microsoft query-antipatterns doc](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/query-antipatterns):
110
+ `FilteringOnCalculatedColumns`, `LargeAmountOfLogicalAttributes`, large-text
111
+ `contains`, leading-wildcard rewrites — all flagged inline AND aggregated
112
+ into an Advisory drawer in the URL bar.
113
+ - **Polymorphic lookup support** — Customer, Owner, and multi-target lookups
114
+ (`regardingobjectid`) emit the correct target-disambiguated
115
+ `<navName>@odata.bind` binding shape automatically.
116
+ - **Code generators** — Every mode emits the same request as
117
+ `Xrm.WebApi.online.execute` (single + `executeMultiple` batch),
118
+ `fetch`, `curl`, and PowerShell `Invoke-RestMethod` snippets. Multi-request
119
+ pipelines (chunked uploads, message-based binary ops) render as full
120
+ ordered sequences.
121
+ - **Saved-request library** — Per-org localStorage persistence with
122
+ auto-suggested names (`account · 3 sel · 2 flt · 2026-05-23`),
123
+ rename / delete / overwrite, dirty-state detection, and cross-tab sync.
124
+ - **PPTB host integration** — `isEmbedded()`-aware UI: theme sync,
125
+ environment-aware URLs, header pass-through, host-stripped header
126
+ advisories. Header / theme controls hide when the host owns them.
127
+
128
+ ---
129
+
130
+ ## 🖼️ Interface overview
131
+
132
+ ```
133
+ ┌─────────────────────────────────────────────────────────────────────────┐
134
+ │ [Request Type ▼] [Group · Method] [⚙ Settings] [Theme] │
135
+ ├──────────────────────────┬──────────────────────────────────────────────┤
136
+ │ │ [Builder] [Code] [Results] │
137
+ │ Sidebar ├──────────────────────────────────────────────┤
138
+ │ │ │
139
+ │ 📋 Target │ Active editor pane │
140
+ │ account │ │
141
+ │ 📊 $select 3 sel │ ┌────────────────────────────────────────┐ │
142
+ │ 🔍 $filter 2 flt │ │ (clause editor — varies per mode) │ │
143
+ │ 🔁 $orderby 1 sort│ │ │ │
144
+ │ 🔗 $expand 1 exp │ │ • Field-set editor (writes) │ │
145
+ │ 📃 $top │ │ • Filter tree (reads) │ │
146
+ │ ⚙ Prefer │ │ • Action param form (executes) │ │
147
+ │ 📥 Headers 1 act │ │ • Binary pipeline (file/image) │ │
148
+ │ │ └────────────────────────────────────────┘ │
149
+ │ ⏱ Recent runs │ │
150
+ │ 200 · 142ms · 32B │ │
151
+ │ 200 · 89ms │ │
152
+ │ │ │
153
+ ├──────────────────────────┴──────────────────────────────────────────────┤
154
+ │ GET /accounts?$select=name,… 0.4 KB ⚠ 2 advisories │
155
+ │ [▶ Execute] │
156
+ └─────────────────────────────────────────────────────────────────────────┘
157
+ ```
158
+
159
+ ---
160
+
161
+ ## 🚀 Getting started
162
+
163
+ ### Prerequisites
164
+
165
+ - [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) (for embedded use)
166
+ - A connection to a Dataverse environment
167
+ - For local development: **Node.js ≥ 20.19** and **npm**
168
+
169
+ ### Installation
170
+
171
+ Dataverse Request Studio is available as a tool in Power Platform ToolBox.
172
+ Install it from the tool gallery or load it as a custom tool.
173
+
174
+ ---
175
+
176
+ ## 🛠️ Development
177
+
178
+ ### Setup
179
+
180
+ ```bash
181
+ git clone https://github.com/mohsinonxrm/pptb-mxrm-dataverse-request-studio.git
182
+ cd pptb-mxrm-dataverse-request-studio
183
+ npm install
184
+ ```
185
+
186
+ ### Common scripts
187
+
188
+ ```bash
189
+ # Vite dev server (standalone, no PPTB host)
190
+ npm run dev
191
+
192
+ # TypeScript-only check (fast)
193
+ npm run typecheck
194
+
195
+ # Production build
196
+ npm run build
197
+
198
+ # Preview the production build locally
199
+ npm run preview
200
+
201
+ # Validate manifest against PPTB registry rules
202
+ npm run validate
203
+
204
+ # Pre-publish: validate → build
205
+ npm run finalize-package
206
+ ```
207
+
208
+ ### Standalone vs PPTB-embedded
209
+
210
+ DRS runs in two modes:
211
+
212
+ - **Standalone** (`npm run dev`) — opens in a regular browser tab. Useful
213
+ for UI iteration. Execute will return `501 Not Implemented` for any
214
+ operation because the host bridge isn't present; you can still build
215
+ requests, preview URLs, and use the Code tab.
216
+ - **Embedded in PPTB** — loads inside the PPTB iframe. The host injects
217
+ `window.dataverseAPI` (typed) and `window.toolboxAPI`. Execute runs
218
+ against the active Dataverse connection.
219
+
220
+ See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for branch conventions,
221
+ commit style, code style, and PR guidance.
222
+
223
+ ---
224
+
225
+ ## 📦 Tech stack
226
+
227
+ | Technology | Version | Purpose |
228
+ |---|---|---|
229
+ | **React** | 18.3 | UI framework |
230
+ | **TypeScript** | 5.9 | Strict mode, discriminated unions |
231
+ | **Vite** | 7 | Build tooling + HMR |
232
+ | **Fluent UI v9** | 9.73 | Microsoft design system (Combobox, DataGrid, Tree, Drawer, Tabs, etc.) |
233
+ | **Monaco Editor** | 0.54 | JSON / code editor for body authoring and Code tab |
234
+ | **@fluentui-contrib/react-data-grid-react-window** | 1.4 | Virtualized results grid |
235
+ | **@dnd-kit** | 6.3 | Drag-reordering for filter / orderby / select clauses |
236
+ | **@pptb/types** | 1.2.1 | Power Platform ToolBox host API types |
237
+
238
+ ---
239
+
240
+ ## 📁 Project layout
241
+
242
+ ```
243
+ src/
244
+ App.tsx — root, ThemedApp, Frame, mode router
245
+ main.tsx — Vite entry point
246
+
247
+ modes/ — one file per request mode (17 modes)
248
+ RetrieveMultipleMode.tsx
249
+ RetrieveSingleMode.tsx
250
+ RetrieveNextLinkMode.tsx
251
+ PredefinedQueryMode.tsx
252
+ CreateMode.tsx / UpdateMode.tsx / UpsertMode.tsx / DeleteMode.tsx
253
+ MergeMode.tsx
254
+ AssociateMode.tsx / DisassociateMode.tsx
255
+ ExecuteActionMode.tsx / ExecuteFunctionMode.tsx / ExecuteWorkflowMode.tsx
256
+ ManageFileMode.tsx / ManageImageMode.tsx / ManageAttachmentMode.tsx
257
+
258
+ editors/ — clause editors shared across modes
259
+ filter/ — FilterEditor + value inputs + operator catalog
260
+ FieldSetEditor.tsx — metadata-driven write-side form
261
+ SelectEditor.tsx, OrderbyEditor.tsx, ExpandEditor.tsx, ApplyEditor.tsx
262
+ ActionParamForm.tsx — CSDL-driven action / function params
263
+ BinarySourceCard.tsx, BinaryPipelineCard.tsx, BinaryColumnPickers.tsx
264
+ HeadersEditor.tsx, BypassEditor.tsx
265
+ ActionPicker.tsx, RecordPicker.tsx, EntityListPicker.tsx
266
+ ...
267
+
268
+ engine/ — URL / body construction + code generation
269
+ urlBuilder.ts — central URL builder for every mode
270
+ executeBuilders.ts — action / function / workflow body builders
271
+ binaryBuilders.ts — file / image / attachment pipelines
272
+ codeGenerators.ts — xrm, xrm-batch, fetch, curl, PowerShell
273
+ runtime.ts — single dispatch point for execute
274
+ dataverseExecutor.ts — live executor over the host's dataverseAPI
275
+ odataParser.ts — round-trips OData URL strings ↔ state
276
+
277
+ host/ — PPTB bridge + metadata loaders
278
+ pptbBridge.ts — typed wrapper over window.dataverseAPI
279
+ metadataProvider.ts — entity / attribute / relationship loaders
280
+ csdlProvider.ts — $metadata XML parsing + action / function index
281
+ cache.ts — singleton TTL cache with in-flight dedup
282
+ useLiveMetadata.ts, useColumnDetail.ts, useScopedEntities.ts, …
283
+
284
+ primitives/ — small reusable UI bits
285
+ Sidebar.tsx, ClauseTreeItem.tsx, SectionHeader.tsx, ModeCard.tsx
286
+ StatusPill.tsx, MethodPill.tsx, AdvisoryDrawer.tsx, advisories.ts
287
+ NavPathColumnPicker.tsx — N:1 drill-down column picker for filter / apply
288
+ KvGrid.tsx, Sortable.tsx, SegmentedToggle.tsx, …
289
+
290
+ shell/ — frame / header / URL bar / tabs / drawers
291
+ Frame.tsx, FrameHeader.tsx, ModeShell.tsx
292
+ UrlBar.tsx, MainTabs.tsx, SettingsDrawer.tsx
293
+
294
+ state/ — per-mode state shapes + persistence
295
+ readState.ts, writeState.ts, relateState.ts, executeState.ts, binaryState.ts
296
+ savedRequests.ts — localStorage persistence (per-org scope)
297
+ SaveContext.tsx — cross-mode save/load context
298
+ displaySettings.ts — display preferences
299
+
300
+ registry/ — request-type catalogue
301
+ requestTypes.ts — 17 request types grouped into 5 groups
302
+
303
+ views/ — output panes
304
+ CodeView.tsx — Code tab: xrm/xrm-batch/fetch/curl/powershell
305
+ ResultsView.tsx — tabs (Detail/Grid/JSON/Headers) + error state
306
+ results/ — grid + cell renderers + flattening
307
+ detail/ — record detail card
308
+
309
+ theme/ — Fluent theme + studio-owned brand vars
310
+ ```
311
+
312
+ ---
313
+
314
+ ## 📋 Web API coverage
315
+
316
+ | Operation | Status |
317
+ |---|---|
318
+ | Retrieve Multiple (full OData) | ✅ |
319
+ | Retrieve Single (by GUID / alt key) | ✅ |
320
+ | `@odata.nextLink` paging | ✅ |
321
+ | Predefined / user queries | ✅ |
322
+ | `$apply` (groupby / aggregate) | ✅ |
323
+ | Lambda filter (`any` / `all`) | ✅ |
324
+ | `$expand` (single + collection, nested) | ✅ |
325
+ | Polymorphic lookups (Customer, Owner, regardingobjectid) | ✅ |
326
+ | Create / Update / Upsert / Delete | ✅ |
327
+ | `Prefer: return=representation` | ✅ |
328
+ | Optimistic concurrency (`If-Match` ETag) | ✅ |
329
+ | `MSCRM.*` bypass family (custom plug-ins, flows, async) | ✅ |
330
+ | Single-property PUT / DELETE | ✅ |
331
+ | Alternate-key upsert | ✅ |
332
+ | Associate / Disassociate (collection + single-valued) | ✅ |
333
+ | Merge (account / contact / incident) | ✅ |
334
+ | Execute Action (OOB / Custom API / Custom Action) | ✅ |
335
+ | Execute Function | ✅ |
336
+ | Execute Workflow | ✅ |
337
+ | File column (upload / download / delete) | ✅ |
338
+ | Image column (thumbnail / full-size) | ✅ |
339
+ | Attachment / Note (inline + message-based) | ✅ |
340
+ | `$batch` envelope composer | ⏳ (see roadmap) |
341
+ | `CreateMultiple` / `UpdateMultiple` / `DeleteMultiple` | ⏳ |
342
+ | `BulkDelete` async job | ⏳ |
343
+ | `ExecuteMultiple` envelope | ⏳ |
344
+
345
+ ---
346
+
347
+ ## 🤝 Contributing
348
+
349
+ See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for branch conventions,
350
+ commit style, code style, repo layout, and PR guidance.
351
+
352
+ ---
353
+
354
+ ## 📋 Roadmap
355
+
356
+ - `$batch` envelope composer mode
357
+ - Bulk-write modes (`CreateMultiple`, `UpdateMultiple`, `DeleteMultiple`)
358
+ - `BulkDelete` async-job composer
359
+ - `ExecuteMultiple` request envelope
360
+ - Recent-runs click-to-reload
361
+ - WriteResultCard "Retrieve this record" cross-mode jump
362
+ - EntitySpecific param — reference vs new-instance toggle
363
+ - Workflow input parameters (parse XAML `InArgument`)
364
+ - Predefined Query — apply to related collection
365
+ - CSV / JSON export from results grid
366
+ - Column resize with persisted widths
367
+ - Smoke-test suite covering URL builders + code generators
368
+
369
+ ---
370
+
371
+ ## 📄 License
372
+
373
+ Licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0-only).
374
+ See [LICENSE](LICENSE) for details.
375
+
376
+ ---
377
+
378
+ ## 🙏 Acknowledgments
379
+
380
+ - [Dataverse REST Builder](https://github.com/GuidoPreite/DRB) - Original inspiration.
381
+ - [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) — host
382
+ platform for the desktop / web app where DRS runs.
383
+ - [FetchXML Studio](https://github.com/mohsinonxrm/pptb-mxrm-fetchxml-studio) — sibling tool that pioneered many of the patterns
384
+ reused here (metadata cache, scope settings, results grid).
385
+ - [Fluent UI](https://react.fluentui.dev/) — UI component library.
386
+ - [Monaco Editor](https://microsoft.github.io/monaco-editor/) — VS Code's editor core.
387
+
388
+ ---
389
+
390
+ Built with ❤️ for the Power Platform community.