Files

Dave 51af6f084d hotfix/2026-02-27 - Reynolds Estimate amounts on second call, + RR Docs in _ref

2026-02-27 16:14:35 -05:00

6.9 KiB

Raw Permalink Blame History

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`)

<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)

<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

Happy path: valid NameRecId, minimal update → StatusCode=0.
Record locked: simulate concurrent change → StatusCode=3.
No updates: send no changing fields → StatusCode=212.
Validation error: bad phone/state/country combination → StatusCode=202.
Customer missing: bad NameRecId → StatusCode=402.
Transport fault: network/timeout; verify retry with same BODId.

6.9 KiB Raw Permalink Blame History Unescape Escape