# 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`.