admin/bodyshop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feature/IO-3255-simplified-parts-management - Beef Up Change Request Parser, add Change Request documentation data

Browse Source
This commit is contained in:
Dave
2025-08-18 12:42:06 -04:00
parent 203cc1ebdf
commit c586d0283b
5 changed files with 457 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
server/integrations/partsManagement/sampleData/schemaDataChange.md Normal file
View File

@@ -0,0 +1,250 @@
You got it—here’s the same style of breakdown for **`VehicleDamageEstimateChgRq`** (the *change
request* variant). I pulled this straight from your XSD set and focused on what differs from
`…AddRq`, what’s required vs optional, and what a minimal-but-valid payload looks like.
---
# What it is & where it lives
* **Global element**: `VehicleDamageEstimateChgRq`
* **Namespace**: `http://www.cieca.com/BMS`
* **Defined in**: `BMSEstimateMessages_2024R1_V6.9.0.xsd`
* **Type**: `EstimateChgRqType` (declared in `BMSEstimateCommonTypes_2024R1_V6.9.0.xsd`)
* **Service group**: `EstimateService` from `BMSEstimateService_2024R1_V6.9.0.xsd`
Group includes: `PropertyDamageEstimateAddRq/Rs`, `VehicleDamageEstimateAddRq/Rs`, *
*`VehicleDamageEstimateChgRq/Rs`**, `VehicleDamagePhotoEstimateAddRq/Rs`.
---
# Top-level schema (for `VehicleDamageEstimateChgRq` → `EstimateChgRqType`)
`EstimateChgRqType` **extends** `MessageHeaderType` (same header as `…AddRq`) but the **body is
almost entirely optional** (intended to send only what’s changing). Only **`DocumentInfo`** is
required.
**Header (inherited from `MessageHeaderType`):**
* **`RqUID`** (UUID) — **required**
* `AsyncRqUID` (UUID) — *optional*
* `PartnerKey` (Identifier) — *optional*
**Body (from `EstimateChgRqType`):**
* `SvcProviderName` (Identifier) — *optional*
* `RefClaimNum` (Char\_50) — *optional*
* **`DocumentInfo`** (`DocumentInfoType`) — **required**
* `ApplicationInfo` (`ApplicationInfoType`) — *optional, 0..*\*\*
* `EventInfo` (`EventInfoType`) — *optional*
* `AdminInfo` (`AdminInfoType`) — *optional*
* `EstimatorIDs` (`EstimatorIDsTypeType`) — *optional*
* `ClaimInfo` (`ClaimInfoType`) — *optional*
* **Choice** — *both optional*:
* `VehicleInfo` (`VehicleInfoType`) — *optional*
* `PropertyInfo` (`PropertyInfoType`) — *optional*
* `ProfileInfo` (`ProfileInfoType`) — *optional*
* `DamageLineInfo` (`DamageLineInfoType`) — *optional, 0..*\*\* (send only changed/affected lines)
* `NonNewOEMPartInd` (Boolean) — *optional*
* `StorageDuration` (Integer\_Range\_0-999) — *optional*
* `RepairTotalsInfo` (`RepairTotalsInfoType`) — *optional, 0..*\*\*
* `RepairTotalsHistory` (`RepairTotalsHistoryType`) — *optional, 0..*\*\*
* `PaymentInfo` (`PaymentInfoType`) — *optional*
* `EstimateMemo` (C) — *optional*
* `AdministrativeMemo` (C) — *optional*
* `Disclaimers` (C) — *optional*
* `CustomMemo` (C) — *optional*
* `CustomPrintImage` (C) — *optional*
* `OtherMemos` (`OtherMemosType`) — *optional, 0..*\*\*
**Key deltas vs `VehicleDamageEstimateAddRq`:**
* `…AddRq` *requires* several containers (`AdminInfo`, `EstimatorIDs`, `ProfileInfo`,
`DamageLineInfo`, `RepairTotalsInfo` with `SummaryTotalsInfo`, etc.).
* `…ChgRq` **only requires** `MessageHeaderType/RqUID` and **`DocumentInfo`**; everything else is
optional so you can send *just what changed*.
* `CalibrationInfo` and `ScanInfo` (present in `…AddRq`) are **not** present in `EstimateChgRqType`.
* Because almost everything is optional, **the burden is on you** to correctly identify the target
document/version in `DocumentInfo` (or via `ReferenceInfo`) and to include all fields necessary
for the receiver to apply your changes.
---
# Important dependent types (same as Add, but optional here)
* **`DocumentInfoType`** (BMSCommonGlobalTypes) — **required**
* Use this to identify *which* estimate you’re changing. Typical:
* **`BMSVer`** = `6.9.0`
* **`DocumentType`** = `E` (estimate)
* `DocumentID` — your estimate ID
* `CreateDateTime` — when you formed this change message
* `ReferenceInfo` — link back to the prior/authoritative doc (e.g., original `DocumentID`/
`DocumentVer`), if your workflow uses references
* `DocumentVer` — version info list, if you lifecycle versions
* **`ApplicationInfoType`** — software fingerprint (optional, 0..\*)
* **`AdminInfoType`** — parties/roles (optional)
* **`EstimatorIDsTypeType`** — supplemental estimator IDs/history (optional)
* **`ClaimInfoType`** — claim-level data (optional)
* **`VehicleInfoType`** (or `PropertyInfoType`) — vehicle path stays under `VehicleInfo` (optional)
* **`ProfileInfoType`** — rates/taxes/rules (optional)
* **`DamageLineInfoType`** — **send changed/added/removed lines only** (your trading partner may
require specific flags/LineStatusCode or use `ParentLineNum`+`UniqueSequenceNum` to identify
updates)
* **`RepairTotalsInfoType`** — updated totals (optional; some partners expect totals to reconcile
with changed lines)
* **`PaymentInfoType`**, memos, custom print/image & `OtherMemos` — all optional
> Because `ChgRq` is sparse by design, **schema validation won’t catch semantic issues** (e.g., you
> remove a part but don’t update totals). Make sure your payload is self-consistent per partner
> rules.
---
# Minimal, schema-valid XML skeleton (change request)
> This represents the *absolute floor* to validate: **Header/RqUID** + **DocumentInfo** with basic
> fields. In practice, include `DocumentID` and some way to reference the prior document/version so
> the receiver can apply changes.
```xml
<VehicleDamageEstimateChgRq xmlns="http://www.cieca.com/BMS">
<!-- MessageHeaderType -->
<RqUID>00000000-0000-0000-0000-000000000000</RqUID>
<!-- EstimateChgRqType sequence -->
<DocumentInfo>
<BMSVer>6.9.0</BMSVer>
<DocumentType>E</DocumentType>
<CreateDateTime>2025-08-14T12:00:00Z</CreateDateTime>
<!-- Strongly recommended for change requests: -->
<!-- <DocumentID>EST-12345</DocumentID> -->
<!-- <DocumentVer>
<DocumentVerCode>REV</DocumentVerCode>
<DocumentVerNum>2</DocumentVerNum>
</DocumentVer>
<ReferenceInfo>
<RefDocumentID>EST-12345</RefDocumentID>
<RefDocumentVerNum>1</RefDocumentVerNum>
</ReferenceInfo> -->
</DocumentInfo>
<!-- Add only what changed. Examples: -->
<!-- Update a rate -->
<!--
<ProfileInfo>
<RateInfo>
<RateType>BODY_LABOR</RateType>
<TaxableInd>true</TaxableInd>
<TaxRate>13.00</TaxRate>
</RateInfo>
</ProfileInfo>
-->
<!-- Add/update a labor line -->
<!--
<DamageLineInfo>
<LineNum>10</LineNum>
<LaborInfo>
<LaborType>BODY</LaborType>
<LaborHours>1.5</LaborHours>
<LaborHourlyRate>85.00</LaborHourlyRate>
</LaborInfo>
</DamageLineInfo>
-->
<!-- Sync totals if your partner requires it with each change -->
<!--
<RepairTotalsInfo>
<SummaryTotalsInfo>
<TotalType>GRAND_TOTAL</TotalType>
<TotalTypeDesc>Grand Total</TotalTypeDesc>
<TotalAmt>1234.56</TotalAmt>
</SummaryTotalsInfo>
</RepairTotalsInfo>
-->
</VehicleDamageEstimateChgRq>
```
---
# Practical guidance & gotchas
1. **Targeting the right document/version**
* `DocumentInfo/DocumentID` + `DocumentVer` and/or `ReferenceInfo` should point unambiguously to the
estimate being changed. This is essential because the schema does **not** include a separate
“ChangeTarget” field—partners expect this info in `DocumentInfo`/`ReferenceInfo`.
2. **Sparsity vs completeness**
* You can send just the changed sections (e.g., one `DamageLineInfo`, one `RateInfo`).
* Some receivers require you to **also** include reconciled `RepairTotalsInfo/SummaryTotalsInfo`.
Check partner specs.
3. **Line identity**
* If you’re updating an existing line, keep its identity stable using `LineNum` and/or
`UniqueSequenceNum`.
* For nested structures, preserve `ParentLineNum`. Use `LineStatusCode` if your partner requires
explicit “added/changed/deleted” flags.
4. **Profile impacts**
* If a change affects pricing (rates, taxes, discounts), update `ProfileInfo` (and possibly totals).
Omitting totals may be acceptable for some partners; others will reject mismatches.
5. **What’s *not* in ChgRq vs AddRq**
* `CalibrationInfo` and `ScanInfo` do not appear in `EstimateChgRqType`. If you need to change those
data, partner workflows may expect a re-send under Add/PhotoAdd or a separate message
family—confirm externally.
6. **Header is still mandatory**
* `RqUID` must be a real UUID.
7. **Code lists**
* Enumerations (e.g., `DocumentType`, `RateType`, `TotalType`, `LaborType`) are validated against
your code list XSDs. Use exact codes.
---
# Quick field checklist for a *solid* ChgRq
* **Header**
* `RqUID` ✅
* **Doc identity**
* `DocumentInfo/BMSVer` = `6.9.0` ✅
* `DocumentInfo/DocumentType` = `E` ✅
* `DocumentInfo/CreateDateTime` ✅
* `DocumentInfo/DocumentID` (recommended) ✅
* `DocumentInfo/DocumentVer` and/or `ReferenceInfo` (recommended) ✅
* **Changed data only**
* `ProfileInfo/RateInfo` (if rates/taxes changed)
* `DamageLineInfo[0..*]` (added/updated/removed lines)
* `RepairTotalsInfo/SummaryTotalsInfo` (if required by partner)
* Any updated `AdminInfo`, `ClaimInfo`, `VehicleInfo` fragments as needed
---
# Pointers to definitions in your bundle
* `VehicleDamageEstimateChgRq` element → `BMSEstimateMessages_2024R1_V6.9.0.xsd`
* `EstimateChgRqType` → `BMSEstimateCommonTypes_2024R1_V6.9.0.xsd`
* `MessageHeaderType`, `DocumentInfoType`, `VehicleInfoType`, `TotalsInfoType`, etc. →
`BMSCommonGlobalTypes_2024R1_V6.9.0.xsd`
* Code lists → `BMSCodeLists_ClassicCode_2024R1_V6.9.0.xsd`,
`BMSCodeLists_CodeExt_2024R1_V6.9.0.xsd`
* Service wrapper → `BMSEstimateService_2024R1_V6.9.0.xsd` (group `EstimateService` contains the
ChgRq/Rs)
---