187 lines
6.9 KiB
Markdown
187 lines
6.9 KiB
Markdown
# Rome – Customer Update (v1.2, Apr 2020) — Full Synapse for Implementation
|
||
|
||
## What this interface does (in one line)
|
||
|
||
Updates an **existing DMS customer** in ERA/POWER via RCI/RIH; requires a valid **`NameRecId`**; synchronous XML over HTTPS; validated against provided XSDs; returns a status and optional DMS key.
|
||
|
||
---
|
||
|
||
## Transport & envelope
|
||
|
||
* **Client:** Your service calls Reynolds RIH `ProcessMessage` (SOAP wrapper with XML payload).
|
||
* **Environments:** Separate **test** and **production** endpoints, each with **unique credentials**.
|
||
* **Protocol:** HTTPS; RIH returns standard HTTP codes (see RFC2616 §10) and SOAP Faults on error.
|
||
* **Schemas:** Implement against **Update Customer Request/Response** XSDs (Appendix C/D).
|
||
|
||
---
|
||
|
||
## Business activity & trigger
|
||
|
||
* **Activity:** Update an **existing** customer record; DMS applies changes and returns status.
|
||
* **Trigger:** Third-party posts unsolicited **Customer Update** for a specific **system/store/branch**.
|
||
* **Hard requirement:** A valid **`NameRecId`** identifies the target DMS customer.
|
||
|
||
---
|
||
|
||
## Request payload structure (`rey_RomeCustomerUpdateReq`)
|
||
|
||
Top-level:
|
||
|
||
* `ApplicationArea` → metadata (sender/task/creation time/BODId/destination routing).
|
||
* `CustRecord` → data blocks to update.
|
||
|
||
### `ApplicationArea`
|
||
|
||
* **`Sender.Component`** = `"Rome"`, **`Sender.Task`** = `"CU"`, **`ReferenceId`** = `"Update"`.
|
||
* **`CreationDateTime`**: dealer local time, ISO-like `YYYY-MM-DD'T'HH:mm:ss`.
|
||
* **`BODId`**: GUID, required for correlation; RIH uses this for tracking.
|
||
* **`Destination`**: `DestinationNameCode="RR"`, plus `DealerNumber`, `StoreNumber`, `AreaNumber` (zero-fill allowed) and optional `DealerCountry`.
|
||
|
||
### `CustRecord`
|
||
|
||
* Attributes: `CustCateg` (`R|W|I`, default `R`), `CreatedBy`.
|
||
* Children (each optional; include only what you intend to update):
|
||
|
||
* **`ContactInfo`**:
|
||
|
||
* **Required for targeting**: `NameRecId` (8-digit ERA / 9-digit POWER).
|
||
* Optional name fields (`LastName`, `FirstName`, `MidName`, `Salut`, `Suffix`).
|
||
* Repeating: `Address` (Type=`P|B`; `Addr1/2`, `City`, `State` **or** `Country`, `Zip`, `County`).
|
||
|
||
* **Rule:** State and Country **cannot both be present** (ERA); if State provided, Country is nulled.
|
||
* Repeating: `Phone` (Type=`H|B|C|F|P|U|O`, `Num`, `Ext`), single `Email.MailTo`.
|
||
* **`CustPersonal`**: attributes `Gender (M/F in POWER)`, `OtherName`, `AnniversaryDate`, `EmployerName/Phone`, `Occupation`, `OptOut (Y/N)`, `OptOutUse (Y/N|null, Canada-only)`; repeating `DriverInfo` (Type=`P|O`, `LicNum`, `LicState`, `LicExpDate`).
|
||
* **`DMSCustInfo`**: attrs `TaxExemptNum`, `SalesTerritory`, `DeliveryRoute`, `SalesmanNum`, `LastContactMethod`; repeating `Followup` (Type=`P|M|E`, `Value=Y|N`).
|
||
|
||
**Most important constraints**
|
||
|
||
* You **must** supply `ContactInfo@NameRecId`.
|
||
* If you send **State**, do **not** send **Country** (ERA rule).
|
||
* Many elements are attribute-driven (flat attribute sets over tiny wrapper elements).
|
||
|
||
---
|
||
|
||
## Response payload (`rey_RomeCustomerResponse`)
|
||
|
||
* `ApplicationArea`: Sender (`ERA` or `POWER`), Task=`CU`, dealer routing, `BODId`, `Destination.DestinationNameCode="RCI"`.
|
||
* `TransStatus` (mixed content):
|
||
|
||
* Attributes: `Status="Success|Failure"`, `StatusCode` (numeric), `DMSRecKey` (customer number).
|
||
* Text node: optional error message text.
|
||
|
||
---
|
||
|
||
## Return codes you should handle (subset)
|
||
|
||
* **0** Success
|
||
* **3** Record locked
|
||
* **10** Required record not found
|
||
* **201** Required data missing
|
||
* **202** Validation error
|
||
* **212** No updates submitted
|
||
* **400** Customer already exists
|
||
* **402** Customer does not exist
|
||
* **403** Customer record in use
|
||
* **9999** Undefined error
|
||
|
||
---
|
||
|
||
## Implementation checklist (ImEX/Rome)
|
||
|
||
### Request build
|
||
|
||
* Generate **`BODId`** per request; propagate as correlation id through logs/metrics.
|
||
* Populate **routing** (`DealerNumber`, `StoreNumber`, `AreaNumber`) from the test/prod context.
|
||
* Ensure **`NameRecId`** is present and valid before sending.
|
||
* Include **only** the fields you intend to update.
|
||
|
||
### Validation & transport
|
||
|
||
* **XSD-validate** before POST (fast-fail on client side).
|
||
* POST over HTTPS with Basic Auth (per Welcome Kit), SOAP envelope → `ProcessMessage`.
|
||
* Treat timeouts/5xx as transient; retry with idempotency keyed by `BODId`.
|
||
|
||
### Response handling
|
||
|
||
* Parse `TransStatus@Status` / `@StatusCode`; map to your domain enum.
|
||
* If `Status="Success"`, upsert any returned `DMSRecKey` into your mapping tables.
|
||
* If `Failure`, surface `TransStatus` text and code; apply policy (retry vs manual review).
|
||
|
||
### Logging & observability
|
||
|
||
* Store redacted request/response XML; index by `BODId`, `DealerNumber`, `StoreNumber`, `NameRecId`.
|
||
* Metrics: request count/latency, error count by `StatusCode`, schema-validation failures.
|
||
|
||
---
|
||
|
||
## Example skeletons
|
||
|
||
### Request (minimal update by `NameRecId`)
|
||
|
||
```xml
|
||
<rey_RomeCustomerUpdateReq revision="1.0" xmlns="http://www.starstandards.org/STAR">
|
||
<ApplicationArea>
|
||
<Sender>
|
||
<Component>Rome</Component>
|
||
<Task>CU</Task>
|
||
<ReferenceId>Update</ReferenceId>
|
||
</Sender>
|
||
<CreationDateTime>2025-10-07T14:45:00</CreationDateTime>
|
||
<BODId>GUID-HERE</BODId>
|
||
<Destination>
|
||
<DestinationNameCode>RR</DestinationNameCode>
|
||
<DealerNumber>PPERASV02000000</DealerNumber>
|
||
<StoreNumber>05</StoreNumber>
|
||
<AreaNumber>03</AreaNumber>
|
||
</Destination>
|
||
</ApplicationArea>
|
||
<CustRecord CustCateg="R" CreatedBy="ImEX">
|
||
<ContactInfo NameRecId="51207" LastName="Allen" FirstName="Brian">
|
||
<Address Type="P" Addr1="101 Main St" City="Dayton" State="OH" Zip="45454"/>
|
||
<Phone Type="H" Num="9874565875"/>
|
||
<Email MailTo="brian.allen@example.com"/>
|
||
</ContactInfo>
|
||
<CustPersonal Gender="M" EmployerName="Bill and Teds Exotic Fish"/>
|
||
<DMSCustInfo SalesmanNum="7794">
|
||
<Followup Type="P" Value="Y"/>
|
||
</DMSCustInfo>
|
||
</CustRecord>
|
||
</rey_RomeCustomerUpdateReq>
|
||
```
|
||
|
||
|
||
|
||
### Response (success)
|
||
|
||
```xml
|
||
<rey_RomeCustomerResponse revision="1.0" xmlns="http://www.starstandards.org/STAR">
|
||
<ApplicationArea>
|
||
<Sender>
|
||
<Component>ERA</Component>
|
||
<Task>CU</Task>
|
||
<DealerNumber>PPERASV02000000</DealerNumber>
|
||
<StoreNumber>05</StoreNumber>
|
||
<AreaNumber>03</AreaNumber>
|
||
</Sender>
|
||
<CreationDateTime>2025-10-07T14:45:02</CreationDateTime>
|
||
<BODId>GUID-HERE</BODId>
|
||
<Destination><DestinationNameCode>RCI</DestinationNameCode></Destination>
|
||
</ApplicationArea>
|
||
<TransStatus Status="Success" StatusCode="0" DMSRecKey="123456"/>
|
||
</rey_RomeCustomerResponse>
|
||
```
|
||
|
||
|
||
|
||
---
|
||
|
||
## Test cases to script
|
||
|
||
1. **Happy path**: valid `NameRecId`, minimal update → `StatusCode=0`.
|
||
2. **Record locked**: simulate concurrent change → `StatusCode=3`.
|
||
3. **No updates**: send no changing fields → `StatusCode=212`.
|
||
4. **Validation error**: bad phone/state/country combination → `StatusCode=202`.
|
||
5. **Customer missing**: bad `NameRecId` → `StatusCode=402`.
|
||
6. **Transport fault**: network/timeout; verify retry with same `BODId`.
|
||
|