Merged PR 2399: Adds characterization coverage and documentation for CRM query field profile
Related work items: #23754
This commit is contained in:
Robert Bond
@@ -0,0 +1,308 @@
|
||||
# Query Profile Compatibility Contract
|
||||
|
||||
## Purpose
|
||||
|
||||
This document records the current compatibility contract around:
|
||||
|
||||
- `actions/selectQueryTypes.js`
|
||||
|
||||
That file is primarily:
|
||||
|
||||
- **CRM/OData query-shape configuration**
|
||||
- **CRM compatibility handling**
|
||||
|
||||
It is **not primarily business-rule logic**.
|
||||
|
||||
Its main job today is to ensure the portal requests the fields that each CRM entity actually exposes so downstream case-summary, representation, status, lifecycle, and infrastructure views continue to function.
|
||||
|
||||
---
|
||||
|
||||
## Source of Truth
|
||||
|
||||
The **CRM field names are the source of truth**.
|
||||
|
||||
The website must query the fields that actually exist on each CRM entity.
|
||||
|
||||
This includes preserving:
|
||||
|
||||
- historic naming differences
|
||||
- spelling mistakes
|
||||
- singular/plural variants
|
||||
- entity-specific field names
|
||||
- legislation-specific field models
|
||||
|
||||
Future work must treat field selection as a **compatibility-sensitive integration concern first**.
|
||||
|
||||
The goal is not to make the query profiles look tidy.
|
||||
|
||||
The goal is to preserve the fields that the live system currently depends on.
|
||||
|
||||
---
|
||||
|
||||
## Appeal-Type Differences
|
||||
|
||||
Different appeal types legitimately require different fields because they support different:
|
||||
|
||||
- legislation
|
||||
- workflows
|
||||
- representation windows
|
||||
- event models
|
||||
- authority models
|
||||
- infrastructure/project processes
|
||||
|
||||
This means:
|
||||
|
||||
- similar-looking appeal types must **not automatically be treated as identical**
|
||||
- near-duplicate field bundles must **not automatically be collapsed**
|
||||
- infrastructure-style entities must **not automatically be forced into planning-style shapes**
|
||||
- minimal profiles must **not automatically be expanded to match richer bundles**
|
||||
|
||||
Bundle-by-bundle evaluation is required.
|
||||
|
||||
---
|
||||
|
||||
## CRM Compatibility Variants
|
||||
|
||||
The current compatibility contract includes representative field variants that must be preserved.
|
||||
|
||||
### Specialist-process variants
|
||||
|
||||
- `pinswg_specialistcaseprocess`
|
||||
- `pinswg_speacialistcaseprocess`
|
||||
|
||||
These are not interchangeable in the current query profiles.
|
||||
|
||||
Representative characterization showed:
|
||||
|
||||
- ROW uses `pinswg_specialistcaseprocess`
|
||||
- Adverts uses `pinswg_speacialistcaseprocess`
|
||||
|
||||
### Start-date variants
|
||||
|
||||
- `pinswg_startdate`
|
||||
- `pinswg_startdates`
|
||||
- `pinswg_applicationacceptedasvalid`
|
||||
|
||||
These reflect different representation-window and process models across entities.
|
||||
|
||||
### Statement-date variants
|
||||
|
||||
- `pinswg_statementduedate`
|
||||
- `pinswg_statementsduedate`
|
||||
|
||||
These must not be normalized away.
|
||||
|
||||
### Project description variants
|
||||
|
||||
- `pinswg_projectdescription`
|
||||
- `pinswg_projectdiscription`
|
||||
|
||||
Harbour Revision Orders currently preserve the misspelled variant.
|
||||
|
||||
### Decision variant
|
||||
|
||||
- `pinswg_dicision`
|
||||
|
||||
Planning S78 currently preserves this field name in its query profile.
|
||||
|
||||
### Other representative compatibility-sensitive variants
|
||||
|
||||
- `pinswg_otherpartiesstatement`
|
||||
- `pinswg_otherpartiesstatements`
|
||||
- `pinswg_otherpartiesstmt`
|
||||
|
||||
- `pinswg_suspensionstartdates`
|
||||
- `pinswg_suspensionstartdate`
|
||||
|
||||
- `pinswg_startdateofevent`
|
||||
- `pinswg_startdateoftheevent`
|
||||
- `pinswg_starttimeofevent`
|
||||
- `pinswg_starttimeoftheevent`
|
||||
- `pinswg_startdatetimeiftheevent`
|
||||
|
||||
These variants must be preserved until characterization-based extraction or change work explicitly proves otherwise.
|
||||
|
||||
---
|
||||
|
||||
## Characterized Field Families
|
||||
|
||||
The current characterization work identifies the following conceptual families already present inside `selectQueryTypes.js`.
|
||||
|
||||
### 1. Planning-style fields
|
||||
|
||||
Representative concerns include:
|
||||
|
||||
- base case identity fields
|
||||
- planning-style address fields
|
||||
- decision/date/status fields
|
||||
- event support fields
|
||||
|
||||
These appear across many planning and enforcement-style entities, but not always with identical field names.
|
||||
|
||||
### 2. Representation-window fields
|
||||
|
||||
Representative fields include:
|
||||
|
||||
- `pinswg_startdate`
|
||||
- `pinswg_startdates`
|
||||
- `pinswg_applicationacceptedasvalid`
|
||||
- `pinswg_statementduedate`
|
||||
- `pinswg_statementsduedate`
|
||||
- `pinswg_finalcommentsduedate`
|
||||
- `pinswg_endofrepresentationperiod`
|
||||
|
||||
These coexist today and reflect different entity models.
|
||||
|
||||
### 3. Specialist-process fields
|
||||
|
||||
Representative fields include:
|
||||
|
||||
- `pinswg_specialistcaseprocess`
|
||||
- `pinswg_speacialistcaseprocess`
|
||||
|
||||
These must not be silently unified.
|
||||
|
||||
### 4. Infrastructure / project fields
|
||||
|
||||
Representative concerns include:
|
||||
|
||||
- project description
|
||||
- project location
|
||||
- submission / publication milestones
|
||||
- recommendation / report fields
|
||||
- suspension dates
|
||||
- grid-reference fields
|
||||
|
||||
These are particularly important in DNS / Harbour / Transport / Electricity style bundles.
|
||||
|
||||
### 5. Authority / LPA fields
|
||||
|
||||
Representative fields include:
|
||||
|
||||
- `_pinswg_localplanningauthority_value`
|
||||
- `_pinswg_associatedlpa_value`
|
||||
- `pinswg_relevantauthorityname`
|
||||
|
||||
These represent different authority models across bundles.
|
||||
|
||||
### 6. Consultation fields
|
||||
|
||||
Representative fields include:
|
||||
|
||||
- `pinswg_consultationopen`
|
||||
- `pinswg_consultationclose`
|
||||
|
||||
These are currently characteristic of SIPS-style profiles.
|
||||
|
||||
### 7. Minimal-profile bundles
|
||||
|
||||
Representative examples include:
|
||||
|
||||
- `pinswg_nonvalidations`
|
||||
- `pinswg_ldps`
|
||||
|
||||
These are intentionally smaller than richer planning and infrastructure bundles.
|
||||
|
||||
---
|
||||
|
||||
## Characterized Divergences
|
||||
|
||||
Characterization work also confirmed that some similar bundles intentionally differ.
|
||||
|
||||
Representative examples:
|
||||
|
||||
### Advert vs ROW specialist-process fields
|
||||
|
||||
- Advert preserves `pinswg_speacialistcaseprocess`
|
||||
- ROW preserves `pinswg_specialistcaseprocess`
|
||||
|
||||
These must not be accidentally collapsed into one shared field choice.
|
||||
|
||||
### Harbour vs DNS project-description fields
|
||||
|
||||
- Harbour preserves `pinswg_projectdiscription`
|
||||
- DNS preserves `pinswg_projectdescription`
|
||||
|
||||
### Suspension-start variants
|
||||
|
||||
- DNS preserves `pinswg_suspensionstartdates`
|
||||
- Harbour and Transport preserve `pinswg_suspensionstartdate`
|
||||
|
||||
### Authority / LPA model differences
|
||||
|
||||
- S78 preserves `_pinswg_localplanningauthority_value`
|
||||
- ROW preserves `_pinswg_associatedlpa_value` plus `pinswg_relevantauthorityname`
|
||||
- DNS preserves `_pinswg_associatedlpa_value` without the planning-style relevant-authority field
|
||||
|
||||
### Event-date and event-time variants
|
||||
|
||||
Representative coexistence includes:
|
||||
|
||||
- `pinswg_startdateofevent`
|
||||
- `pinswg_startdateoftheevent`
|
||||
- `pinswg_starttimeofevent`
|
||||
- `pinswg_starttimeoftheevent`
|
||||
- `pinswg_startdatetimeiftheevent`
|
||||
|
||||
### Representation-support differences in similar bundles
|
||||
|
||||
Representative differences include:
|
||||
|
||||
- singular vs plural other-parties fields
|
||||
- singular vs plural statement-due-date fields
|
||||
- bundle-specific combinations of proof/questionnaire/final-comments fields
|
||||
|
||||
These differences must be treated as compatibility-sensitive unless explicitly re-characterized.
|
||||
|
||||
---
|
||||
|
||||
## Future Guidance
|
||||
|
||||
Future work in this area should follow these rules:
|
||||
|
||||
1. **Characterize first**
|
||||
- prove current behaviour before changing structure
|
||||
|
||||
2. **Extract later**
|
||||
- do not extract shared bundles or constants until the current compatibility contract is protected
|
||||
|
||||
3. **Preserve compatibility**
|
||||
- CRM field variants are not “cleanup noise”; they are part of the current live contract
|
||||
|
||||
4. **Evaluate bundle-by-bundle**
|
||||
- each bundle should be assessed on its own actual field requirements
|
||||
|
||||
5. **Avoid broad normalization**
|
||||
- do not assume similar names mean safe consolidation
|
||||
|
||||
6. **Protect intentional differences**
|
||||
- especially for:
|
||||
- specialist-process fields
|
||||
- representation-window fields
|
||||
- project-description fields
|
||||
- suspension-start fields
|
||||
- authority/LPA fields
|
||||
- event-date/time fields
|
||||
|
||||
The safest sequence remains:
|
||||
|
||||
- characterize current bundles
|
||||
- characterize current families
|
||||
- characterize duplicated clusters and divergences
|
||||
- only then consider bounded extraction work
|
||||
|
||||
---
|
||||
|
||||
## Explicit Non-Goals
|
||||
|
||||
This characterization and documentation work does **not**:
|
||||
|
||||
- rename CRM fields
|
||||
- remove typo fields
|
||||
- redesign CRM entities
|
||||
- standardize legislation-specific data
|
||||
- force appeal types into identical query profiles
|
||||
- introduce a query DSL
|
||||
- move this concern into a broader business-rule domain boundary
|
||||
|
||||
Any future cleanup or extraction must preserve the documented compatibility contract unless an explicit behaviour-change decision is made.
|
||||
Reference in New Issue
Block a user