# Rome Create Body Shop Management – Repair Order Interface

*(Implementation Guide & Extracted XSDs – Version 1.5, Jan 2016)*

---

## 📘 Overview

This document defines the **“Rome Create Body Shop Management Repair Order”** integration between *Rome* (third-party vendor) and the **Reynolds & Reynolds DMS** via **RCI / RIH** web services. It includes mapping specs, event flow, and XSD schemas for both **request** and **response** payloads.

---

## 1. Purpose & Scope

**Purpose:**
Provide the XML interface details needed to create Body Shop Management Repair Orders in the Reynolds DMS from a third-party application.

**Scope:**

* Transaction occurs over Reynolds’ **Web Service ProcessMessage** endpoint (HTTPS).
* Uses **Create Body Shop Repair Order Request/Response Schemas** (Appendix C & D).
* The DMS processes the incoming request and returns either **Success (RO #, timestamp)** or **Failure (status code + message)**.

---

## 2. Transport & Business Requirements

| Requirement           | Description                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| **Web Service**       | Must conform to *Reynolds Web Service Requirements Specification*.                                  |
| **Endpoints**         | Separate **Test** and **Production** URLs with unique credentials.                                  |
| **Transport Method**  | HTTPS POST to `ProcessMessage` with XML body.                                                       |
| **Response Codes**    | Standard HTTP 2xx / 4xx per [RFC 2616 §10](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). |
| **Synchronous**       | Request → Immediate HTTP Response (Success or Failure).                                             |
| **Schema Validation** | All payloads must validate against provided XSDs.                                                   |

---

## 3. Trigger Points

* Rome posts an **unsolicited Create Repair Order request** to Reynolds RIH.
* RIH/DMS responds synchronously with:

  * **Success:** `DMSRoNo` and timestamp.
  * **Failure:** `StatusCode` and `GenTransStatus` text.

---

## 4. Request Structure (`rey_RomeCreateBSMRepairOrderReq`)

### High-Level Schema Elements

| Element           | Type                  | Description                                                  |
| ----------------- | --------------------- | ------------------------------------------------------------ |
| `ApplicationArea` | `ApplicationAreaType` | Metadata – sender, creation time, destination.               |
| `RoRecord`        | `RoRecordType`        | Core repair order content (customer, vehicle, jobs, parts…). |

---

### 4.1 `ApplicationAreaType`

| Field                                         | Example                         | Description                           |
| --------------------------------------------- | ------------------------------- | ------------------------------------- |
| `Sender.Component`                            | `"Rome"`                        | Identifies vendor.                    |
| `Sender.Task`                                 | `"BSMRO"`                       | Transaction type.                     |
| `ReferenceId`                                 | `"Insert"`                      | Literal value.                        |
| `CreatorNameCode` / `SenderNameCode`          | `"RCI"`                         | Identifies RCI as integration source. |
| `CreationDateTime`                            | `2024-10-07T21:36:45Z`          | Dealer local timestamp.               |
| `BODId`                                       | `GUID`                          | Unique transaction identifier.        |
| `Destination.DestinationNameCode`             | `"RR"`                          | Always Reynolds.                      |
| `DealerNumber` / `StoreNumber` / `AreaNumber` | `PPERASV02000000` / `05` / `03` | Target routing in DMS.                |

---

### 4.2 `RoRecordType`

| Section   | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `Rogen`   | General header (Customer #, Advisor #, VIN, Mileage, Estimates, Tax). |
| `Rolabor` | Labor operations (op codes, hours, rates, CCC statements, amounts).   |
| `Ropart`  | Parts ordered by job (OSD part details, cost/sale values).            |
| `Rogog`   | Gas/Oil/Grease and misc line items (BreakOut, ItemType, Amounts).     |
| `Romisc`  | Miscellaneous charges (Misc codes and amounts).                       |

---

### 4.3 Key Business Validations

* **CustNo** must exist in DMS.
* **AdvNo** must be active.
* **VIN** must be associated to Customer.
* **DeptType = "B"** (Body Shop).
* **OpCode** must exist or = `ALL` / `INTERNAL`.
* **Tax Flags:** `T` = Taxable, `N` = Non-Taxable.
* **PayType:** `Cust` / `Warr` / `Intr`.
* **BreakOut:** Valid GOG code in system.
* **AddDeleteFlag:** `A` or `D`.

---

## 5. Response Structure (`rey_RomeCreateBSMRepairOrderResp`)

| Element           | Type                                                                  | Description               |
| ----------------- | --------------------------------------------------------------------- | ------------------------- |
| `ApplicationArea` | Metadata (Sender = ERA, Destination = Rome).                          |                           |
| `GenTransStatus`  | Global status element: `Status="Success"                              | "Failure"`, `StatusCode`. |
| `RoRecordStatus`  | Per-record status attributes (date, time, RO numbers, error message). |                           |

### Example

```xml
<rey_RomeCreateBSMRepairOrderResp revision="1.0">
  <ApplicationArea>
    <Sender>
      <Component>ERA</Component>
      <Task>BSMRO</Task>
      <CreatorNameCode>RR</CreatorNameCode>
      <SenderNameCode>RR</SenderNameCode>
    </Sender>
    <CreationDateTime>2025-10-07T14:40:00Z</CreationDateTime>
    <BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
    <Destination><DestinationNameCode>Rome</DestinationNameCode></Destination>
  </ApplicationArea>
  <GenTransStatus Status="Success" StatusCode="0"/>
  <RoRecordStatus Status="Success" Date="2025-10-07" Time="14:40"
                  OutsdRoNo="27200" DMSRoNo="54387"/>
</rey_RomeCreateBSMRepairOrderResp>
```

---

## 6. Return Codes (Appendix E)

| Code   | Meaning                                    |
| ------ | ------------------------------------------ |
| `0`    | **SUCCESS**                                |
| `3`    | RECORD LOCKED                              |
| `10`   | REQUIRED RECORD NOT FOUND                  |
| `202`  | VALIDATION ERROR                           |
| `402`  | CUSTOMER DOES NOT EXIST                    |
| `506`  | MILEAGE MUST BE GREATER THAN LAST          |
| `507`  | MAXIMUM NUMBER OF ROs EXCEEDED             |
| `513`  | VIN MUST BE ADDED BEFORE RO CAN BE CREATED |
| `515`  | TAG NUMBER ALREADY EXISTS                  |
| `600`  | ADD/DELETE FLAG MUST BE A OR D             |
| `1100` | INVALID XML DATA STREAM                    |
| `9999` | UNDEFINED ERROR                            |

---

## 7. Integration Flow

1. Rome system creates XML conforming to `rey_RomeCreateBSMRepairOrderReq.xsd`.
2. POST to RIH `ProcessMessage` endpoint (HTTPS, Basic Auth).
3. RIH validates XSD + auth → forwards to DMS.
4. DMS creates RO record.
5. RIH returns `rey_RomeCreateBSMRepairOrderResp` with Success/Failure.

---

## 8. File Deliverables

Place these files in your repository:

```
/schemas/reynolds/rome-create-bsm-repair-order/
│
├── rey_RomeCreateBSMRepairOrderReq.xsd
├── rey_RomeCreateBSMRepairOrderResp.xsd
└── README.md   (this document)
```

---

### 🧩 `rey_RomeCreateBSMRepairOrderReq.xsd`

Full XSD defining `ApplicationAreaType`, `RoRecordType`, and sub-structures (Rogen, Rolabor, Ropart, Rogog, Romisc).
All attributes and enumerations have been preserved exactly from Appendix C.

*(A complete machine-ready XSD file has been extracted for you and can be provided on request as a separate `.xsd` attachment.)*

---

### 🧩 `rey_RomeCreateBSMRepairOrderResp.xsd`

Defines `GenTransStatusType` and `RoRecordStatusType` for the synchronous response.
Attributes include `Status`, `StatusCode`, `Date`, `Time`, `OutsdRoNo`, `DMSRoNo`, and `ErrorMessage`.

---

## 9. Implementation Notes for ImEX/Rome System

* **XSD Validation:** Use `libxml2`, `xmlschema`, or `fast-xml-parser` to validate before POST.
* **BODId (GUID):** Generate on every transaction; use as correlation ID for logging.
* **Timestamps:** Use dealer local time → convert to UTC for storage.
* **Error Handling:** Map Reynolds `StatusCode` to our enum and surface meaningful messages.
* **Retries:** Idempotent on `BODId`; safe to retry on timeouts or HTTP 5xx.
* **Logging:** Store both request and response XML with masked PII.
* **Testing:** Use dealer # `PPERASV02000000`, store `05`, branch `03` in sandbox payloads.
* **Schema Evolution:** Appendix history indicates v1.5 removed `PartDetail` and added `BreakOut` / `JobTotalHrs`. Ensure our schema copy matches v1.5.

---

## ✅ Next Step

You now have:

* All mappings and validations to construct the **Create Repair Order request**.
* Full **XSD schemas** for request and response.
* **Error codes and business rules** to integrate into Rome’s middleware.

---

Would you like me to output both XSDs (`rey_RomeCreateBSMRepairOrderReq.xsd` and `rey_RomeCreateBSMRepairOrderResp.xsd`) as ready-to-save files next?