dsh-d365-kit 0.0.0-stage → 0.34.3
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/CHANGELOG.md +318 -0
- package/CHANGELOG.zh-CN.md +317 -0
- package/INSTALL.md +94 -0
- package/INSTALL.zh-CN.md +93 -0
- package/LICENSE +21 -0
- package/README.md +335 -2
- package/README.zh-CN.md +336 -0
- package/client.js +1818 -0
- package/cordis.patch.yml +44 -0
- package/docs/en/architecture.md +172 -0
- package/docs/en/checks.md +184 -0
- package/docs/en/installation.md +151 -0
- package/docs/en/permissions.md +161 -0
- package/docs/en/scenarios.md +202 -0
- package/docs/en/tools.md +665 -0
- package/docs/en/troubleshooting.md +131 -0
- package/docs/zh/architecture.md +172 -0
- package/docs/zh/checks.md +184 -0
- package/docs/zh/installation.md +151 -0
- package/docs/zh/permissions.md +161 -0
- package/docs/zh/scenarios.md +202 -0
- package/docs/zh/tools.md +665 -0
- package/docs/zh/troubleshooting.md +131 -0
- package/examples/prompts.en.md +206 -0
- package/examples/prompts.zh-CN.md +206 -0
- package/examples/waivers.example.json +20 -0
- package/icon.svg +6 -0
- package/index.js +142 -0
- package/lib/auth.js +181 -0
- package/lib/client.js +496 -0
- package/lib/code-check.js +549 -0
- package/lib/config.js +323 -0
- package/lib/contract-history.js +49 -0
- package/lib/contract.js +583 -0
- package/lib/csharp-check.js +493 -0
- package/lib/data-migrate.js +1318 -0
- package/lib/data-policy.js +78 -0
- package/lib/error-codes.js +80 -0
- package/lib/errors.js +81 -0
- package/lib/gitlab.js +161 -0
- package/lib/health.js +205 -0
- package/lib/migrate.js +732 -0
- package/lib/preflight.js +116 -0
- package/lib/refs.js +191 -0
- package/lib/resources.js +320 -0
- package/lib/retention-defaults.js +17 -0
- package/lib/retention.js +384 -0
- package/lib/runtime.js +232 -0
- package/lib/settings-http.js +512 -0
- package/lib/settings-store.js +371 -0
- package/lib/skill.js +76 -0
- package/lib/snapshot.js +149 -0
- package/lib/tool-code-check.js +133 -0
- package/lib/tool-configure.js +169 -0
- package/lib/tool-contract.js +376 -0
- package/lib/tool-data-sync.js +559 -0
- package/lib/tool-data-write.js +203 -0
- package/lib/tool-data.js +282 -0
- package/lib/tool-diff.js +484 -0
- package/lib/tool-environments.js +106 -0
- package/lib/tool-flows.js +540 -0
- package/lib/tool-health.js +127 -0
- package/lib/tool-invoke.js +284 -0
- package/lib/tool-layers.js +497 -0
- package/lib/tool-metadata.js +417 -0
- package/lib/tool-migrate.js +102 -0
- package/lib/tool-refs.js +206 -0
- package/lib/tool-reports.js +299 -0
- package/lib/tool-sync.js +430 -0
- package/lib/tool-trace.js +420 -0
- package/lib/tool-write.js +563 -0
- package/lib/waivers.js +83 -0
- package/lib/write-actions.js +1374 -0
- package/lib/write-policy.js +199 -0
- package/lib/write-store.js +167 -0
- package/locale/en.json +68 -0
- package/locale/zh.json +68 -0
- package/package.json +59 -4
- package/skills/d365-troubleshooting/SKILL.md +115 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# Permissions & Writes
|
|
2
|
+
|
|
3
|
+
**English** | [简体中文](../zh/permissions.md)
|
|
4
|
+
|
|
5
|
+
## Default posture
|
|
6
|
+
|
|
7
|
+
Right after installation the plugin is **read-only**:
|
|
8
|
+
|
|
9
|
+
- Metadata (entities, fields, forms, views, plugins, solutions, layers, sitemaps…) is governed by `metadata.read`, which is **on by default** — an environment that is not listed explicitly counts as granted;
|
|
10
|
+
- **Business records** are not readable by default; grant `data.read` per environment;
|
|
11
|
+
- Any change needs the matching capability granted per environment, and every execution needs a human confirmation.
|
|
12
|
+
|
|
13
|
+
"What you can see" and "what you can change" share one per-environment capability table, because the two belong together. The page renders one block per environment, separated by a rule.
|
|
14
|
+
|
|
15
|
+
## Capability table
|
|
16
|
+
|
|
17
|
+
Configured in `d365.config.json`:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"write": {
|
|
22
|
+
"capabilityVersion": 2,
|
|
23
|
+
"environments": {
|
|
24
|
+
"dev": ["metadata.read", "data.read", "optionValue.add", "attribute.add", "view.columns"],
|
|
25
|
+
"sit": ["metadata.read", "data.read"],
|
|
26
|
+
"uat": []
|
|
27
|
+
},
|
|
28
|
+
"solutionUniqueName": "ContosoBase"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- An environment with **no entry** has never been configured and keeps the default (only `metadata.read`);
|
|
34
|
+
- An environment whose entry is an **empty array** has everything revoked, including metadata;
|
|
35
|
+
- `capabilityVersion` is written by the settings page when it saves. Older files (without the field) get `metadata.read` added back to their existing entries, which preserves the pre-upgrade "metadata is always readable" behaviour.
|
|
36
|
+
|
|
37
|
+
| Capability | Real HTTP operation | Group | Effect |
|
|
38
|
+
| --- | --- | --- | --- |
|
|
39
|
+
| `metadata.read` | metadata `GET` | Metadata | Read tables/fields/forms/views/plugins/layers (on by default) |
|
|
40
|
+
| `data.read` | business-data `GET` | Data | Read business records |
|
|
41
|
+
| `data.write` | `POST` / `PATCH` | Data | Create or update business records (high risk, no deletions) |
|
|
42
|
+
| `optionValue.add` | `InsertOptionValue` | Option set | Add option values (global or field-local) |
|
|
43
|
+
| `optionValue.updateLabel` | `UpdateOptionValue` | Option set | Change option labels |
|
|
44
|
+
| `optionValue.delete` | `DeleteOptionValue` | Option set | **Permanently delete** option values (high risk) |
|
|
45
|
+
| `attribute.add` | `POST EntityDefinitions(...)/Attributes` | Field | Add fields |
|
|
46
|
+
| `attribute.update` | `PUT` field URL (`MSCRM.MergeLabels`) | Field | Change display name, description, required level |
|
|
47
|
+
| `attribute.delete` | `DELETE` field URL | Field | **Permanently delete** the field and its data (high risk) |
|
|
48
|
+
| `entity.update` | `PUT` entity URL (`MSCRM.MergeLabels`) | Table | Change table display name and description |
|
|
49
|
+
| `view.columns` | `PATCH savedqueries(id)` | View | Add or remove columns in system views (`layoutxml` only) |
|
|
50
|
+
| `layer.remove` | `RemoveActiveCustomizations` | Layer | **Permanently remove** the top-most unmanaged layer of a component (high risk; tables, fields, global option sets, forms, views, workflows, web resources, plug-ins, custom APIs) |
|
|
51
|
+
| `message.invoke` | any `POST` action | Message | Call one Dataverse message. The message is implemented by the target environment's plug-ins, so it may write data, send notifications or call external systems (high risk; every call is confirmed in the chat) |
|
|
52
|
+
|
|
53
|
+
Tick them per environment under Permissions in the settings page; "Copy to all environments" is supported.
|
|
54
|
+
|
|
55
|
+
## Three gates, one decision point
|
|
56
|
+
|
|
57
|
+
The decision lives in one place, `lib/client.js`, so a new tool cannot bypass it — every request (including "test connection" in the settings page) goes through it:
|
|
58
|
+
|
|
59
|
+
- **Metadata read**: the entity set name in the request URL is on the metadata allowlist (`EntityDefinitions`, `systemforms`, `savedqueries`, `webresourceset`, `solutions`, `msdyn_componentlayers`…) and requires `metadata.read`; it fails with `metadata-read-forbidden`;
|
|
60
|
+
- **Business-data read**: every other `GET` is blocked as business data and requires `data.read`; it fails with `data-read-forbidden`;
|
|
61
|
+
- **Write**: a request that is not `GET` and does not belong to a metadata message (`PublishXml`, `InsertOptionValue`, `CreateAttribute`, `RemoveActiveCustomizations`…) must have `data.write` first, otherwise it fails with `data-write-forbidden`. A `d365_invoke` `POST` goes through `message.invoke` instead (failing as `message-invoke-forbidden`), while its `GET` function is still a read and needs `data.read`.
|
|
62
|
+
|
|
63
|
+
Every gate fires **before a token is acquired**, so the request never reaches the environment. Decisions are cached per environment for 2 seconds, so a change in the settings page applies to the next tool call.
|
|
64
|
+
|
|
65
|
+
## Two-step writes
|
|
66
|
+
|
|
67
|
+
### Step 1: generate a plan (read-only)
|
|
68
|
+
|
|
69
|
+
`plan-*` reads the current state, skips items with no change, writes the operations to a plan file (`.d365/pending-writes/`) and returns the operation list.
|
|
70
|
+
|
|
71
|
+
| Plan | Constraint |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| `plan-add-options` | Dedupes by the code before `\|`; new values continue from the current maximum +1; existing codes go to `skipped` |
|
|
74
|
+
| `plan-relabel` | Only items whose label actually changes go into the plan |
|
|
75
|
+
| `plan-option-delete` | Requires `acknowledge: true`; missing values go to `skipped`, and Dataverse refuses the delete when existing records reference the value |
|
|
76
|
+
| `plan-add-attribute` | The table must exist and the field must not; `SchemaName` must carry the publisher prefix |
|
|
77
|
+
| `plan-update-attribute` | Only items that really change are included |
|
|
78
|
+
| `plan-delete-attribute` | Requires `acknowledge: true`, otherwise it is rejected outright |
|
|
79
|
+
| `plan-update-entity` | Changes the display name / description only |
|
|
80
|
+
| `plan-view-columns` | Locates the system view by view name (same name distinguished by `entity`); only the cell list in `layoutxml` changes, filter conditions are left alone |
|
|
81
|
+
|
|
82
|
+
Local option sets (an option set carried by a field) are addressed with `entity` + `attribute`; global option sets with `optionSet`.
|
|
83
|
+
|
|
84
|
+
### Step 2: execute (needs a human)
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
Run mw04aul6-1ci6aa
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The agent calls `d365_write action=execute planId=...`, which:
|
|
91
|
+
|
|
92
|
+
1. Reads the plan and checks that its status is `pending`;
|
|
93
|
+
2. Checks that the environment **still** holds this capability;
|
|
94
|
+
3. Checks whether the environment is importing/publishing (see below);
|
|
95
|
+
4. Shows a confirmation card: environment, targets, operation count, the first 10 operations; with deletions it adds an unrecoverable warning;
|
|
96
|
+
5. Click "Execute now" → operations are written one by one → publish runs in the background → the run is audited.
|
|
97
|
+
|
|
98
|
+
You can also review and execute from the Pending changes tab in the settings page (the same second, red confirmation). Both entry points share the same checks.
|
|
99
|
+
|
|
100
|
+
### Plan states
|
|
101
|
+
|
|
102
|
+
`pending → running → done / failed`
|
|
103
|
+
|
|
104
|
+
`running` is persisted before the first write, so a process killed midway never leaves behind a plan that still looks clickable. For a plan that is not `pending`, both the tool and the settings page **refuse** to execute or cancel it — writes are not idempotent, and a rerun would resubmit the parts that already took effect. To redo the work, generate a new plan.
|
|
105
|
+
|
|
106
|
+
### Pre-flight check
|
|
107
|
+
|
|
108
|
+
Dataverse holds a customization lock while importing or publishing. Microsoft first-party updates arrive as solution imports, and an environment spends a large part of the day doing exactly that — during which writes either fail with `0x80071151` or wait for the lock until they time out.
|
|
109
|
+
|
|
110
|
+
So before executing, the plugin looks for rows in `msdyn_solutionhistories` where `msdyn_endtime` is null:
|
|
111
|
+
|
|
112
|
+
| Case | Behavior |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| A row exists and its start time is within `busyWindowMinutes` (default 120 minutes) | Refuse to execute and report the operation in progress (`environment-busy`) |
|
|
115
|
+
| Only older rows (leftover zombie rows) | Do not block; mention it in the result |
|
|
116
|
+
| The table cannot be queried (no permission) | Skip the check and note in the result that it was skipped |
|
|
117
|
+
|
|
118
|
+
`force: true` skips it; use it only when you are sure the row is a leftover.
|
|
119
|
+
|
|
120
|
+
### Default solution
|
|
121
|
+
|
|
122
|
+
Every metadata change is recorded in some **solution layer**. Without a solution it goes into the active default layer (Default Solution), which does not travel with an exported solution, and downstream this shows up as "the field does not exist".
|
|
123
|
+
|
|
124
|
+
So fill in "Default solution for changes": the unique name of an **existing unmanaged** solution. It is validated at plan time — a name that does not exist fails with `unknown-solution`, a managed one with `managed-solution`, instead of waiting until execution to fail.
|
|
125
|
+
|
|
126
|
+
### Publish scope
|
|
127
|
+
|
|
128
|
+
After writing, only the **affected components** are published:
|
|
129
|
+
|
|
130
|
+
- Option set operations → the corresponding option set (field-local option set → the table that owns it);
|
|
131
|
+
- Field / table / view operations → the table that owns them.
|
|
132
|
+
|
|
133
|
+
The payload looks like:
|
|
134
|
+
|
|
135
|
+
```xml
|
|
136
|
+
<importexportxml>
|
|
137
|
+
<entities><entity>account</entity></entities>
|
|
138
|
+
<optionsets><optionset>contoso_taxcategoryos</optionset></optionsets>
|
|
139
|
+
</importexportxml>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
One publish takes seconds to a dozen seconds, instead of the minutes `PublishAllXml` needs to recompute two thousand-plus tables. Only when the affected components cannot be derived does it fall back to a full publish. Publishing happens in the background, the result is written to `.d365/changes/publish-<planId>.json`, and the execute response carries `publishState` (`skipped` / `running`).
|
|
143
|
+
|
|
144
|
+
## Writing business data
|
|
145
|
+
|
|
146
|
+
Three constraints on `d365_data_write`:
|
|
147
|
+
|
|
148
|
+
- It needs `data.write`, off by default;
|
|
149
|
+
- It can write to **one** environment only;
|
|
150
|
+
- Every write shows a confirmation card; the request goes out only after approval.
|
|
151
|
+
|
|
152
|
+
Writes need no publish (business data is not metadata). The audit records field names only, never values. There is no delete.
|
|
153
|
+
|
|
154
|
+
## Safety boundaries
|
|
155
|
+
|
|
156
|
+
- **Write endpoints accept only the settings page**: `/write/policy`, `/write/cancel`, `/write/execute`, `/write/publish` require an `x-d365-meta-write: 1` header. A cross-site page must pass a CORS preflight to send that header, and these routes never answer preflights; if the request carries an `Origin`, it must also be same-origin. The auth channel rewrites the URL to `http://dsh.internal` and swallows `Origin`, so Origin alone cannot be the test. Rejected requests are logged to `.d365/write-guard.log`.
|
|
157
|
+
- **Retries only for safe methods**: `GET`/`HEAD` retry on network errors and 5xx; `POST`/`PATCH`/`DELETE` retry only on **429** (the server explicitly did not execute). A write timeout is reported as "may have taken effect", for a human to check in the environment, rather than being silently resent.
|
|
158
|
+
- **Republishing passes the same gate**: the environment must still hold the capability it had at the time, and an idle check runs first (a busy environment returns 409 rather than a raw 429).
|
|
159
|
+
- **Cancel rejects non-`pending` just like execute**: there is no "the page says cancelled while the backend keeps writing".
|
|
160
|
+
- **No rollback**: metadata deletions cannot be undone, so a delete requires `acknowledge: true`, and the card calls it out separately.
|
|
161
|
+
- Write endpoints expose no bulk script entry point and no "skip confirmation" switch; `force` skips only the idle check, never the confirmation.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Usage Scenarios
|
|
2
|
+
|
|
3
|
+
**English** | [简体中文](../zh/scenarios.md)
|
|
4
|
+
|
|
5
|
+
Everything below can be said to the agent as-is. Tool arguments are in brackets; the agent fills them in itself.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Taking over an environment: get the lay of the land
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
Connect to all four environments and see what each one is doing.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
d365_envs check=true
|
|
17
|
+
d365_health allEnvironments=true hours=24
|
|
18
|
+
d365_metadata resource=organization
|
|
19
|
+
d365_metadata resource=solutions top=10 orderby="installedon desc"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
What you get: whether each environment is reachable, its org version, hung/failed jobs, imports and publishes in progress, and what was installed recently.
|
|
23
|
+
|
|
24
|
+
This is the first step before answering any "does the environment have X" — it keeps you from mistaking "not configured" for "not present in the environment".
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 2. Can this field be deleted?
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Which forms, views, and workflows still use contoso_customertier on account? Also check how many records still carry a value.
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
d365_refs kind=field entity=account attribute=contoso_customertier allEnvironments=true
|
|
36
|
+
d365_data action=group entity=account field=contoso_customertier top=10
|
|
37
|
+
d365_layers component=contoso_customertier componentType=Attribute entity=account
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Three pieces of evidence together:
|
|
41
|
+
|
|
42
|
+
- **References**: 17 forms, 64 views (62 columns / 50 filters), 0 workflows/business rules;
|
|
43
|
+
- **Data**: the distribution of records that have a value for the field (empty is its own bucket);
|
|
44
|
+
- **Layers**: who added the field and which solution owns the active layer — if it comes from a managed solution you cannot delete it locally, only the publisher can change it.
|
|
45
|
+
|
|
46
|
+
The delete itself is `d365_write action=plan-delete-attribute ... acknowledge=true`, but you usually use these three pieces of evidence to convince people first.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 3. Why two environments differ
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
Sync forms, views, and fields from DEV and SIT, tell me the differences, then explain why the Account form differs.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
d365_sync environments=["dev","sit"] resources=["forms","views","solutions"] includeAttributes=true entities=["account"]
|
|
58
|
+
d365_diff base=dev head=sit resources=["forms","views","attributes"]
|
|
59
|
+
d365_layers component=Account componentType=SystemForm allEnvironments=true
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`d365_diff` gives the mechanical difference (which rows were added/removed, which fields changed); `d365_layers` gives the reason (who overrode it, who sits on top).
|
|
63
|
+
|
|
64
|
+
Noise is already handled: timestamps and `*id` columns are not compared, and `organization` is skipped by default. When form content differs a lot, the field-level diff in the report reads far better than a wall of XML.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 4. Assessing a solution before release
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
What are the risks of shipping ContosoBase from DEV to SIT and UAT?
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
d365_migrate action=assess source=dev solution=ContosoBase targets=["sit","uat"]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The report answers:
|
|
79
|
+
|
|
80
|
+
- whether the targets have this solution, and whether the source version is newer;
|
|
81
|
+
- who owns the top layer of each component in the target, and which solutions' definitions get shadowed after import (shadowed solutions are listed, sorted by component count);
|
|
82
|
+
- whether option set values will be lost (a value the source has and the target lacks = critical; mismatched labels = warning);
|
|
83
|
+
- which components the target is missing;
|
|
84
|
+
- when the source is unmanaged, the layer the import creates cannot be cleared by uninstalling a solution.
|
|
85
|
+
|
|
86
|
+
A real case: for a solution holding just 1 global option set, the assessment can come back as "0 critical, 2 warnings, but it will invalidate the definitions of 7 solutions" — the decision that actually matters is not about losing data, it is that **the next time anyone imports a Contoso patch, that layer gets covered again**.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 5. Checking whether an MR can ship to UAT
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
https://gitlab.example.com/contoso/powerapps/-/merge_requests/7759/diffs will this MR cause problems if it goes to UAT?
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
d365_code_check mergeRequest="https://gitlab.example.com/contoso/powerapps/-/merge_requests/7759/diffs" targets=["uat"]
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Three sections come out:
|
|
101
|
+
|
|
102
|
+
- **Blockers**: a field is on none of the forms that load the library, an entity does not exist, a deleted function is still referenced by a handler, a C# type/step/image is missing;
|
|
103
|
+
- **Warnings**: a field is only on some forms, the assembly version was not bumped, a hard-coded GUID;
|
|
104
|
+
- **Manual confirmation**: configuration data, secure configuration, privileges, ambiguity between a column name and a plain key.
|
|
105
|
+
|
|
106
|
+
The report is at `.d365/reports/code-check-<MR>-<timestamp>.md`.
|
|
107
|
+
|
|
108
|
+
C#-only MRs work too: infer the assembly from the project directory → exact match → look up types/steps/images/filtering attributes. Assembly names are matched exactly only; guessing wrong is worse than not checking.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 6. Filling in a batch of option values
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
contoso_taxcategoryos is still missing 36 tax registration number types; add them to DEV from the list in .d365/reports.
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
d365_write action=plan-add-options environment=dev optionSet=contoso_taxcategoryos \
|
|
120
|
+
labels=["AD3|Andorra: Tax Register Number (NRT)", "..."]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The plan returns the list of operations (values continue from the current maximum +1; codes that already exist go into skipped). Once checked:
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
Run mw04aul6-1ci6aa
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A card pops up in the conversation → approve → write → publish only this option set. The audit trail is in `.d365/changes/`, the publish result in `.d365/changes/publish-<planId>.json`.
|
|
130
|
+
|
|
131
|
+
**Do not append them by hand in the remaining environments**: let them ride along with the solution import, otherwise the next time someone imports a managed patch your hand-added layer gets covered.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 7. Upstream changed a plugin — what is downstream missing
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
Has SIT and UAT caught up with DEV's plugin registrations? Also check whether any scripts referenced by forms are missing.
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
d365_contract action=drift source=dev targets=["sit","uat"] forms=true
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Typical result (real data): 86 findings = 4 missing assemblies, 72 missing plugin steps, 8 missing types, 2 missing form libraries.
|
|
146
|
+
`forms=false` skips reading formxml; `handlers=true` downloads scripts to check that the functions exist (slow, up to 400 scripts per environment).
|
|
147
|
+
|
|
148
|
+
Register a waiver for differences that are genuinely allowed:
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
d365_contract action=waive rule=form-library-missing env=sit \
|
|
152
|
+
object="/_static/_common/scripts/CommandbarActions.js" reason="this environment does not use SLA dialogs" days=30
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The next run over the same `source → targets` reports a trend of "N new / M gone".
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 8. Publish is stuck / can I write now
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
Is any import or publish running in the four environments right now? I want to change some metadata.
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
d365_health allEnvironments=true
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
If an environment has a `Publish` or an import in progress, any write gets `0x80071151` or waits until the lock times out. Wait for it to finish; `d365_write execute` checks this step itself and refuses outright when the environment is busy instead of throwing a raw 429.
|
|
170
|
+
|
|
171
|
+
Only use `force: true` once you have confirmed that record is a leftover (for example, an import that was interrupted days ago).
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## 9. Disk is bloated by artifacts
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
How big is .d365 now? What can be cleaned up?
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
d365_reports action=list
|
|
183
|
+
d365_reports action=cleanup target=query # dry run only by default
|
|
184
|
+
d365_reports action=cleanup target=query dryRun=false
|
|
185
|
+
d365_reports action=compact # compact snapshot JSON to one line
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Real data: four full snapshots take about 540 MB, and compacting to one line saves 68 MB; within a single snapshot, `plugin_steps.json` is about 55 MB, `solution_components.json` about 39 MB, and `web_resources.json` about 20 MB.
|
|
189
|
+
|
|
190
|
+
For the retention policy and automatic cleanup, see [tools.md](tools.md#d365_reports) and the [root README](../../README.md).
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Combined usage
|
|
195
|
+
|
|
196
|
+
| Question | Combination |
|
|
197
|
+
| --- | --- |
|
|
198
|
+
| Is it safe to change this field | `d365_refs` + `d365_data` + `d365_layers` |
|
|
199
|
+
| Can this version ship | `d365_health` + `d365_migrate` + `d365_contract` |
|
|
200
|
+
| Can this MR merge | `d365_code_check` + `d365_refs` |
|
|
201
|
+
| Where do the environments differ | `d365_sync` + `d365_diff` + `d365_layers` |
|
|
202
|
+
| Why does it fail at runtime | `d365_refs` (field/script references) + `d365_layers` (who overrides) + `d365_health` (jobs) |
|