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