hotfix/2026-02-27 - Reynolds Estimate amounts on second call, + RR Docs in _ref
This commit is contained in:
Dave
@@ -0,0 +1,222 @@
|
||||
# Rome Technologies – Customer Insert Interface
|
||||
|
||||
*(Implementation Guide & Extracted XSDs – Version 1.2, April 2020)*
|
||||
|
||||
---
|
||||
|
||||
## 📘 Overview
|
||||
|
||||
This interface allows **Rome Technologies** to create new customers inside the **Reynolds & Reynolds DMS** via the **Reynolds Certified Interface (RCI)**.
|
||||
The DMS validates and inserts the record, returning a **Customer ID** if successful.
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose & Scope
|
||||
|
||||
* **Purpose :** Provide XML schemas and mapping for inserting new customer records into the DMS.
|
||||
* **Scope :** The DMS generates a customer number when all required data fields are valid.
|
||||
|
||||
* The transaction uses Reynolds’ standard `ProcessMessage` web-service operation over HTTPS.
|
||||
* Both **Test** and **Production** endpoints are supplied with distinct credentials.
|
||||
|
||||
---
|
||||
|
||||
## 2. Transport & Event Requirements
|
||||
|
||||
| Property | Requirement |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| **Protocol** | HTTPS POST to `/ProcessMessage` (SOAP envelope). |
|
||||
| **Auth** | Basic Auth (username / password) — unique per environment. |
|
||||
| **Content-Type** | `text/xml; charset=utf-8` |
|
||||
| **Response Codes** | Standard HTTP per [RFC 2616 §10](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). |
|
||||
| **Schemas** | `rey_RomeCustomerInsertReq.xsd`, `rey_RomeCustomerInsertResp.xsd`. |
|
||||
| **Synchronous** | Immediate HTTP 2xx or SOAP Fault. |
|
||||
| **Return Data** | `DMSRecKey`, `StatusCode`, and optional error message. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Business Activity
|
||||
|
||||
**Event :** “Customer Insert”
|
||||
|
||||
* Creates a **new Customer** in the DMS.
|
||||
* The DMS assigns a **Customer Number** if all validations pass.
|
||||
* Errors yield status codes and messages from Appendix E.
|
||||
|
||||
---
|
||||
|
||||
## 4. Trigger Points & Flow
|
||||
|
||||
1. Rome posts `rey_RomeCustomerInsertReq` XML to Reynolds RIH.
|
||||
2. RIH validates schema + auth → forwards to DMS.
|
||||
3. DMS creates customer record → returns response object.
|
||||
4. Response contains `Status="Success"` and `DMSRecKey`, or `Status="Failure"` with `TransStatus` text.
|
||||
|
||||
### Sequence Diagram (Conceptual)
|
||||
|
||||
```
|
||||
Rome → RIH/DMS: ProcessMessage (InsertCustomer)
|
||||
RIH → Rome: rey_RomeCustomerResponse (Success/Failure)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Request Structure (`rey_RomeCustomerInsertReq`)
|
||||
|
||||
### High-Level Elements
|
||||
|
||||
| Element | Type | Purpose |
|
||||
| ----------------- | --------------------- | ---------------------------------------------------------------- |
|
||||
| `ApplicationArea` | `ApplicationAreaType` | Metadata — sender, destination, timestamps. |
|
||||
| `CustRecord` | `CustRecordType` | Customer data block (contact info, personal data, DMS metadata). |
|
||||
|
||||
---
|
||||
|
||||
### 5.1 ApplicationAreaType
|
||||
|
||||
| Field | Example | Notes |
|
||||
| --------------------------------- | -------------------------------------- | --------------------------- |
|
||||
| `Sender.Component` | `"Rome"` | Vendor identifier. |
|
||||
| `Sender.Task` | `"CU"` | Transaction code. |
|
||||
| `ReferenceId` | `"Insert"` | Always literal. |
|
||||
| `CreationDateTime` | `2025-10-07T10:23:45` | Dealer local time. |
|
||||
| `BODId` | `ef097f3a-01b2-1eca-b12a-80048cbb74f3` | Unique GUID for tracking. |
|
||||
| `Destination.DestinationNameCode` | `"RR"` | Target system. |
|
||||
| `DealerNumber` | `PPERASV02000000` | Performance Path system id. |
|
||||
| `StoreNumber` | `05` | Zero-padded. |
|
||||
| `AreaNumber` | `03` | Branch number. |
|
||||
|
||||
---
|
||||
|
||||
### 5.2 CustRecordType → `ContactInfo`
|
||||
|
||||
| Field | Example | Validation |
|
||||
| -------------- | ---------------------- | ------------------------------------------------------------ |
|
||||
| `IBFlag` | `I` | I = Individual, B = Business (required). |
|
||||
| `LastName` | `Allen` | Required. |
|
||||
| `FirstName` | `Brian` | Required if Individual. |
|
||||
| `Addr1` | `101 Main St` | Required. |
|
||||
| `City` | `Dayton` | Required. |
|
||||
| `State` | `OH` | Cannot coexist with `Country`. |
|
||||
| `Zip` | `45454` | Valid ZIP or postal. |
|
||||
| `Phone.Type` | `H` | H/B/C/F/P/U/O (Home/Business/Cell/Fax/Pager/Unlisted/Other). |
|
||||
| `Phone.Num` | `9874565875` | Digits only. |
|
||||
| `Email.MailTo` | `customer@example.com` | Optional. |
|
||||
|
||||
---
|
||||
|
||||
### 5.3 CustPersonal Block
|
||||
|
||||
| Field | Example | Notes |
|
||||
| ----------------------- | --------------------------- | ------------------------ |
|
||||
| `Gender` | `M` | Must be M or F. |
|
||||
| `BirthDate.date` | `1970-01-01` | Type = P/O. |
|
||||
| `SSNum.ssn` | `254785986` | 9-digit numeric. |
|
||||
| `DriverInfo.LicNum` | `HU987458` | License Number. |
|
||||
| `DriverInfo.LicState` | `OH` | 2-letter state. |
|
||||
| `DriverInfo.LicExpDate` | `2026-07-27` | Expiration date. |
|
||||
| `EmployerName` | `Bill and Teds Exotic Fish` | Optional. |
|
||||
| `OptOut` | `Y/N` | Marketing opt-out. |
|
||||
| `OptOutUse` | `Y/N/null` | Canada-only use consent. |
|
||||
|
||||
---
|
||||
|
||||
### 5.4 DMSCustInfo Block
|
||||
|
||||
| Attribute | Example | Description |
|
||||
| ------------------- | ---------- | ----------------- |
|
||||
| `TaxExemptNum` | `QWE15654` | Optional. |
|
||||
| `SalesTerritory` | `1231` | Optional. |
|
||||
| `DeliveryRoute` | `1231` | Optional. |
|
||||
| `SalesmanNum` | `7794` | Sales rep code. |
|
||||
| `LastContactMethod` | `phone` | Optional text. |
|
||||
| `Followup.Type` | `P/M/E` | Phone/Mail/Email. |
|
||||
| `Followup.Value` | `Y/N` | Consent flag. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Response Structure (`rey_RomeCustomerResponse`)
|
||||
|
||||
| Element | Description |
|
||||
| ----------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `ApplicationArea` | Metadata (Sender = ERA or POWER, Task = CU). |
|
||||
| `TransStatus` | Text node with optional error message. Attributes = `StatusCode`, `Status`, `DMSRecKey`. |
|
||||
| `Status` values | `"Success"` or `"Failure"`. |
|
||||
| `StatusCode` | Numeric code from Appendix E. |
|
||||
| `DMSRecKey` | Generated Customer Number (e.g., `123456`). |
|
||||
|
||||
---
|
||||
|
||||
### Example Success Response
|
||||
|
||||
```xml
|
||||
<rey_RomeCustomerResponse revision="1.0">
|
||||
<ApplicationArea>
|
||||
<Sender>
|
||||
<Component>ERA</Component>
|
||||
<Task>CU</Task>
|
||||
<CreatorNameCode>RR</CreatorNameCode>
|
||||
<SenderNameCode>RR</SenderNameCode>
|
||||
<DealerNumber>PPERASV02000000</DealerNumber>
|
||||
<StoreNumber>05</StoreNumber>
|
||||
<AreaNumber>03</AreaNumber>
|
||||
</Sender>
|
||||
<CreationDateTime>2025-10-07T14:30:00</CreationDateTime>
|
||||
<BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
|
||||
<Destination><DestinationNameCode>RCI</DestinationNameCode></Destination>
|
||||
</ApplicationArea>
|
||||
<TransStatus Status="Success" StatusCode="0" DMSRecKey="123456"/>
|
||||
</rey_RomeCustomerResponse>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Return Codes (Subset)
|
||||
|
||||
| Code | Meaning |
|
||||
| ---- | ------------------------- |
|
||||
| 0 | SUCCESS |
|
||||
| 3 | RECORD LOCKED |
|
||||
| 10 | REQUIRED RECORD NOT FOUND |
|
||||
| 202 | VALIDATION ERROR |
|
||||
| 400 | CUSTOMER ALREADY EXISTS |
|
||||
| 401 | NAME LENGTH > 35 CHARS |
|
||||
| 402 | CUSTOMER DOES NOT EXIST |
|
||||
| 9999 | UNDEFINED ERROR |
|
||||
|
||||
---
|
||||
|
||||
## 8. Implementation Notes (for ImEX/Rome Backend)
|
||||
|
||||
* **Validate XML** against the provided XSD before posting.
|
||||
* **Generate GUID** (BODId) for each request and store with logs.
|
||||
* **Log Request/Response** payloads (mask PII).
|
||||
* **Handle duplicate customers** gracefully (`400` code).
|
||||
* **Map DMSRecKey → local customer table** on success.
|
||||
* **Retries:** idempotent on `BODId`; safe to retry 5xx or timeouts.
|
||||
* **Alerting:** notify on `StatusCode ≠ 0`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Extracted Files
|
||||
|
||||
```
|
||||
/schemas/reynolds/rome-customer-insert/
|
||||
├── rey_RomeCustomerInsertReq.xsd
|
||||
├── rey_RomeCustomerInsertResp.xsd
|
||||
└── README.md (this document)
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ✅ Next Steps
|
||||
|
||||
1. Integrate `InsertCustomer` into your Reynolds connector module.
|
||||
2. Validate XML using the above schemas.
|
||||
3. Log and map responses into your CRM / body-shop customer table.
|
||||
4. Prepare test suite for codes 0, 202, 400, 402, 9999.
|
||||
|
||||
---
|
||||
|
||||
*Source : Rome Technologies Customer Insert Specification v1.2 (Apr 2020) – Reynolds & Reynolds Certified Interface Documentation.*
|
||||
Reference in New Issue
Block a user