pptb-entity-fields-analyzer 0.0.0-stage → 1.0.0

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,3 +1,134 @@
1
- # Temporary Holding Version
1
+ ![Entity Fields Analyzer icon](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/public/icon/entity-fields-analyzer.svg)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Entity Fields Analyzer (Power Platform ToolBox)
4
+
5
+ Entity Fields Analyzer for [Power Platform ToolBox](https://www.powerplatformtoolbox.com/) is the web version of the Entity Fields Analyser XrmToolBox plugin. It answers four questions about a Dataverse / Dynamics 365 table:
6
+
7
+ - What are its fields, and where do they come from?
8
+ - Which fields are really filled, and which are never used?
9
+ - How much room is left before the limit of 1,024 columns?
10
+ - What should be cleaned up first?
11
+
12
+ | Page | What it does |
13
+ |---|---|
14
+ | **Overview** | Key figures, field types, origin (standard / custom, managed / unmanaged), field settings, custom fields per publisher prefix, fields created over time. Click a chart or a tile to list its fields. |
15
+ | **Fields** | Every field with its metadata (32 more columns with *All metadata columns*), quick filters, type filter, search, sort. |
16
+ | **Data usage** | Fill rate of each field, never used and rarely used fields, distribution, fill rate by type, least used custom fields. |
17
+ | **Capacity** | Estimate of the physical columns used, what consumes them, and a calculator for the fields you plan to add. |
18
+ | **Export to Excel** | One workbook: metadata, dashboard with native charts, summary, recommendations, data usage, by type, by publisher, lookups, timeline. |
19
+
20
+ Nothing is read until you click **Get Entities**. The interface and the report are available in English and French.
21
+
22
+ ## Screenshots
23
+
24
+ Demo data from the end-to-end tests.
25
+
26
+ **Overview**: every chart opens the matching fields.
27
+
28
+ ![Overview of the fields of a table](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/docs/screenshots/overview.png)
29
+
30
+ **Fields**: the fields empty in every record are highlighted.
31
+
32
+ ![Fields with their metadata and fill rate](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/docs/screenshots/fields.png)
33
+
34
+ **Data usage**: the clean-up candidates.
35
+
36
+ ![Data usage of the fields](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/docs/screenshots/data-usage.png)
37
+
38
+ **Capacity**: plan new fields before creating them.
39
+
40
+ ![Column capacity and calculator](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/docs/screenshots/capacity.png)
41
+
42
+ **Dark theme**: the tool follows the theme of the ToolBox.
43
+
44
+ ![Overview in the dark theme](https://raw.githubusercontent.com/AmraouiH/EntityFieldsAnalyzer-PPTB/main/docs/screenshots/overview-dark.png)
45
+
46
+ ## How to use
47
+
48
+ 1. Open the tool with a Dataverse connection and click **Get Entities**.
49
+ 2. Filter or search the list, then click an entity (a double-click analyses it right away).
50
+ 3. Choose **Metadata only**, or **Metadata + Data usage** to also measure how full each field is.
51
+ 4. Click **Analyse**. **Stop** or **Esc** interrupts an analysis; no partial result is kept.
52
+ 5. Click **Export to Excel** to save the report.
53
+
54
+ ## What this tool changes
55
+
56
+ **Nothing in Dataverse.** The tool only sends read requests: it never creates, updates, deletes or publishes anything.
57
+
58
+ On your computer, it writes the Excel report when you export it, and three preferences in the ToolBox settings (language, entity filter, metadata columns).
59
+
60
+ ## Data and network
61
+
62
+ - The tool calls only the connected Dataverse environment, through the ToolBox. It declares no external host and sends no telemetry.
63
+ - Data usage reads the records of the table in memory, page by page, and keeps only a counter per field. No record value is stored or exported.
64
+
65
+ ## How the figures are computed
66
+
67
+ - **Analysed fields**: readable attributes, without virtual, party list, composite and companion attributes (`AttributeOf`). Multi-select choices, files and images are virtual attributes, so they are not analysed.
68
+ - **Fill rate**: share of the records read where the field has a value. `0`, `No` and an empty text are values.
69
+ - **Column capacity** is an estimate with the weights below, against 1,024 columns.
70
+
71
+ | Field type | Columns |
72
+ |---|---|
73
+ | Lookup, Owner | 3 |
74
+ | Option set, Money, Boolean, Status | 2 |
75
+ | Any other type | 1 |
76
+
77
+ Background: [Field limits in Dynamics 365: how many fields is too many fields?](https://hamzaamraoui.medium.com/field-limits-in-dynamics-365-how-many-fields-is-too-many-fields-ab39c699336e)
78
+
79
+ ## Known limitations
80
+
81
+ - **Permissions**: only what your account can read is counted. Records you cannot see are left out, and secured fields you cannot read look empty. Check with a privileged account before deleting a field.
82
+ - **Large tables**: data usage reads every record, so it can take a long time and it counts toward the service protection limits of Dataverse. The ToolBox rejects responses over 16 MB, so pages are sized to the records and the scan restarts with smaller pages when one is still too large.
83
+ - **Unpublished changes** are included when Dataverse accepts `RetrieveEntity`. Otherwise the tool reads the published metadata and says so.
84
+
85
+ ## Build
86
+
87
+ Requirements: Node.js 20.19 or later.
88
+
89
+ ```bash
90
+ npm install
91
+ npm run build # type-check + vite build -> dist/
92
+ npm run dev-watch # development build with source maps, rebuilt on save
93
+ npm run validate # pptb-validate
94
+ ```
95
+
96
+ ## Automated tests
97
+
98
+ ```bash
99
+ npm run test:logic # metadata, paging, capacity, recommendations, Excel
100
+ npm run test:e2e # headless Edge / Chrome against an in-memory Dataverse and ToolBox
101
+ ```
102
+
103
+ The end-to-end tests open the production bundle with a content security policy like the one of the ToolBox. They fail on any write, extra header or console error. Set `EFA_SHOTS` and `EFA_XLSX` to folders to keep the screenshots and workbooks, and `PW_BROWSER` if your browser is not in a standard location.
104
+
105
+ ## Load in Power Platform ToolBox
106
+
107
+ 1. Run `npm run build`.
108
+ 2. In Power Platform ToolBox, open **Settings**, turn on **Show Debug Menu**, and select **Save**.
109
+ 3. In the **Debug** section, under **Load Local Tool**, select **Browse**, pick this folder (the one that contains `package.json`), then select **Load Tool**.
110
+ 4. Open **Entity Fields Analyzer** and pick a connection.
111
+
112
+ ## Publish
113
+
114
+ 1. Update `version` in `package.json`.
115
+ 2. Run `npm run build`, `npm run validate`, then `npm run finalize-package`.
116
+ 3. Run `npm publish --access public`.
117
+ 4. Submit the package at https://www.powerplatformtoolbox.com/submit-tool.
118
+
119
+ ## AI Assistance
120
+
121
+ A substantial part of the code, the tests and this documentation was written with an AI coding assistant (Claude Code, by Anthropic).
122
+ See the [AI-Assisted Development policy](https://docs.powerplatformtoolbox.com/policies/ai-assisted-development).
123
+
124
+ ## Credits
125
+
126
+ Port of the [Entity Fields Analyser XrmToolBox plugin](https://github.com/AmraouiH/Entity-Field-Analyser) by Hamza AMRAOUI, republished here by its author under the MIT license.
127
+
128
+ ## Support
129
+
130
+ If the tool helps you, you can support its development on [PayPal](https://www.paypal.com/paypalme/EntityFieldsAnalyser). Bugs and ideas: [GitHub issues](https://github.com/AmraouiH/EntityFieldsAnalyzer-PPTB/issues).
131
+
132
+ ## License
133
+
134
+ MIT