215 lines
9.5 KiB
Markdown
215 lines
9.5 KiB
Markdown
# 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?
|