admin/bodyshop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Dave
2026-02-27 16:14:35 -05:00
parent e03546d989
commit 51af6f084d
11 changed files with 1684 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
_reference/reynolds/documentation/Convenient Brands RCI Welcome Kit.pdf.md Normal file
View File

@@ -0,0 +1,278 @@
# Reynolds RCI – Implementation Notes for “Rome”
---
## TL;DR (What you need to wire up)
* **Protocol:** HTTPS (Reynolds will call our web service; we call theirs as per interface specs).
* **Auth:** Username/Password and/or client certs. **No IP allowlisting** (explicitly disallowed).
* **Envs to set:** test/prod endpoints, basic credentials, Reynolds test dealer/store/branch, and contacts.
* **Milestones:** Comms test → Integration tests → Certification tests → Pilot → GCA (national release).
* **Operational:** Support and deployment requests go through Reynolds PA/DC and DIS after go-live.
---
## Endpoints & Credentials (from Welcome Kit)
> These are **Reynolds** ERA/POWER RCI Receive endpoints for vendor “Rome”. Keep in a secure secret store.
| Environment | URL | Login | Password |
| ----------- | -------------------------------------------------------- | ------ | -------------- |
| **TEST** | `https://b2b-test.reyrey.com/Sync/RCI/Rome/Receive.ashx` | `Rome` | `p7Q7RLXwO8IB` |
| **PROD** | `https://b2b.reyrey.com/Sync/RCI/Rome/Receive.ashx` | `Rome` | `93+?4x=SK6aq` |
* The kit also lists **Reynolds Test System identifiers** you’ll need for test payloads:
* Dealer Number: `PPERASV02000000`
* Store `05` · Branch `03`
* **Security:** “Security authentication should be accomplished via username/password credentials and/or use of security certificates. **IP whitelisting is not permitted.**”
---
## Our App Configuration (env/secret template)
Create `apps/server/.env.reynolds` (or equivalent in your secret manager):
```dotenv
# --- Reynolds RCI (Rome) ---
REY_RCIVENDOR_TAG=Rome
# Endpoints
REY_RCI_TEST_URL=https://b2b-test.reyrey.com/Sync/RCI/Rome/Receive.ashx
REY_RCI_PROD_URL=https://b2b.reyrey.com/Sync/RCI/Rome/Receive.ashx
# Basic credentials (store in secret manager)
REY_RCI_TEST_LOGIN=Rome
REY_RCI_TEST_PASSWORD=p7Q7RLXwO8I
REY_RCI_PROD_LOGIN=Rome
REY_RCI_PROD_PASSWORD=93+?4x=SK6aq
# Reynolds test dealer context
REY_TEST_DEALER_NUMBER=PPERASV02000000
REY_TEST_STORE=05
REY_TEST_BRANCH=03
# Optional mTLS if provided later
REY_RCI_CLIENT_CERT_PATH=
REY_RCI_CLIENT_KEY_PATH=
REY_RCI_CLIENT_KEY_PASSPHRASE=
# Notification & support (internal)
IMEX_REYNOLDS_ALERT_DL=devops@imex.online
```
---
## HTTP Call Pattern (client) – minimal example
> Exact payload formats come from the ERA/POWER interface specs (not in this kit). Use these stubs to wire transport & auth now; plug actual SOAP/XML later.
### Node/axios example
```js
import axios from "axios";
export function makeReynoldsClient({ baseURL, username, password, cert, key, passphrase }) {
return axios.create({
baseURL,
timeout: 30000,
httpsAgent: cert && key
? new (await import("https")).Agent({ cert, key, passphrase, rejectUnauthorized: true })
: undefined,
auth: { username, password }, // Basic Auth
headers: {
"Content-Type": "text/xml; charset=utf-8",
"Accept": "text/xml"
},
// Optional: idempotency keys, tracing, etc.
});
}
// Usage (TEST):
const client = makeReynoldsClient({
baseURL: process.env.REY_RCI_TEST_URL,
username: process.env.REY_RCI_TEST_LOGIN,
password: process.env.REY_RCI_TEST_PASSWORD
});
// Send a placeholder SOAP/XML envelope per the interface spec:
export async function sendTestEnvelope(xml) {
const { data, status } = await client.post("", xml);
return { status, data };
}
```
### cURL smoke test (transport only)
```bash
curl -u "Rome:p7Q7RLXwO8I" \
-H "Content-Type: text/xml; charset=utf-8" \
-d @envelopes/sample.xml \
"https://b2b-test.reyrey.com/Sync/RCI/Rome/Receive.ashx"
```
> Replace `@envelopes/sample.xml` with your valid envelope from the spec.
---
## Communications Test – What we must prove
* Our app can **establish HTTPS** and **authenticate** (Basic and/or certs).
* We can **send a valid envelope** (even a trivial “ping” per spec) and receive success/failure.
* Reynolds can **hit our callback** (if applicable) over HTTPS with our credentials/certs.
* **No IP allowlisting** dependencies. Log end-to-end request/response with redaction.
* Ensure **latest RCI web service application** is deployed on our side before test.
### Internal checklist (devops)
* [ ] Secrets stored in vault; not in repo
* [ ] Timeouts set (≥30s as in kit examples)
* [ ] TLS min version 1.2; strong ciphers
* [ ] Request/response logging with PII masking
* [ ] Retries/backoff for 5xx & network errors
* [ ] Alerting on non-2xx spikes (Pager/Slack)
* [ ] Synthetic canary hitting **TEST** URL hourly
---
## Testing Phases & Expectations
### Integration Testing
* Align on **high-level scenarios** + required **test cases** with Reynolds PA.
* Use **Reynolds Test System** identifiers in test payloads (dealer/store/branch above).
### Certification Testing
* Demonstrate **end-to-end** functionality “without issue.”
* After sign-off, PA coordinates move to **pilot**.
---
## Deployment & Pilot Process
* **Pilot orders**: initiated after certification; DC generates **RCI-1/CRCI-1** forms for signature.
* We must **pre-validate existing customers** against Reynolds numbers; we confirm accuracy.
* Maintain a list of **authorized signers** (officer-signed form required).
* **EULA on file** is required to permit data sharing to us per **RIA**.
* Dealer is notified by RCI Deployment when setup completes.
**Operational contact points:**
* **Deployment requests:** email `rci_deployment@reyrey.com`.
* **Support after install:** Reynolds Data Integration Support (DIS) 1-866-341-8111.
---
## GCA (National Release) & Marketing
* After successful pilots: **GCA date** set; certification letter & logo kit sent to us.
* RCI website updated to show **Certified** status.
* Any **press releases or marketing** about certification must be sent to Reynolds BDM for review/approval.
* BDM (from kit): **Amanda Gorney** – `Amanda_Gorney@reyrey.com` – 937-485-1775.
---
## Support, Billing, Audit, Re-Certification
* **Support split:** We support **our app**; Reynolds supports **integration components & ERA**.
* **Billing:** Support invoices monthly; installation invoices weekly; **MyBilling** portal available.
* **Audit:** Periodic audits of customer lists and EULA status.
* **Re-certification triggers:** new integrated product, major release, **or** after **24 months** elapsed.
---
## Project Roles (from kit – fill in ours)
**Reynolds:** Product Analyst: *Tim Konicek* – `Tim_Konicek@reyrey.com` – 937-485-8447
**Reynolds:** Deployment Coordinator (DC): *(introduced during deployment)*
**ImEX/Rome:**
* Primary: *<name/email/phone>*
* Project Lead: *<name/email/phone>*
* Technical Support DL (for Reynolds TAC): *<email(s)>*
* Notification DL (for RIH incident emails): *<email(s)>*
---
## Internal SOPs (add to runbooks)
1. **Before Comms Test**
* [ ] Deploy latest RCI web service app build.
* [ ] Configure secrets + TLS.
* [ ] Verify outbound HTTPS egress to Reynolds test host.
2. **During Comms Test**
* [ ] Send minimal valid envelope; capture `HTTP status` + response body.
* [ ] Record request IDs/correlation IDs for Reynolds.
3. **Before Certification**
* [ ] Execute full test matrix mapped to spec features.
* [ ] Produce **evidence pack** (logs, payloads, results).
4. **Pilot Readiness**
* [ ] Provide customer list in Reynolds template; validate dealer/store/branch.
* [ ] Submit authorized signers form (officer-signed).
* [ ] Confirm EULA on file per RIA.
---
## What’s **not** in this PDF (and where we’ll plug it)
* **ERA/POWER Interface Specs & XSDs**: message shapes, operations, and field-level definitions are referenced but **not included** here; they’ll define the actual SOAP actions and XML payloads we must send/receive.
* Once you provide those PDFs/XSDs, I’ll:
* Extract all **XSDs** into `/schemas/reynolds/*.xsd`.
* Generate **sample envelopes** in `/envelopes/`.
* Add **validator scripts** and **TypeScript types** (xml-js / xsd-ts).
* Flesh out **per-operation** client wrappers and test cases.
> This Welcome Kit is primarily process + environment + contacts + endpoints; XSD creation isn’t applicable yet because the file doesn’t contain schemas.
---
## Appendices
### A. Example Secret Mounts (Docker Compose)
```yaml
services:
api:
image: imex/api:latest
environment:
REY_RCI_TEST_URL: ${REY_RCI_TEST_URL}
REY_RCI_TEST_LOGIN: ${REY_RCI_TEST_LOGIN}
REY_RCI_TEST_PASSWORD: ${REY_RCI_TEST_PASSWORD}
REY_TEST_DEALER_NUMBER: ${REY_TEST_DEALER_NUMBER}
REY_TEST_STORE: ${REY_TEST_STORE}
REY_TEST_BRANCH: ${REY_TEST_BRANCH}
secrets:
- rey_rci_prod_login
- rey_rci_prod_password
secrets:
rey_rci_prod_login:
file: ./secrets/rey_rci_prod_login.txt
rey_rci_prod_password:
file: ./secrets/rey_rci_prod_password.txt
```
### B. Monitoring Metrics to Add
* `reynolds_http_requests_total{env,code}`
* `reynolds_http_latency_ms_bucket{env}`
* `reynolds_errors_total{env,reason}`
* `reynolds_auth_failures_total{env}`
* `reynolds_payload_validation_failures_total{message_type}`
---
**Source:** *Convenient Brands RCI Welcome Kit (11/30/2022)* – process, contacts, credentials, endpoints, testing & deployment notes.
---
*Ready for the next PDF. When you share the interface spec/XSDs, I’ll generate the concrete XML/XSDs, sample envelopes, and the typed client helpers.*

214
_reference/reynolds/documentation/Rome Create Body Shop Management Repair Order Interface Specification.pdf.md Normal file
View File

@@ -0,0 +1,214 @@
# 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?

222
_reference/reynolds/documentation/Rome Customer Insert Specification 1.2.pdf.md Normal file
View File

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

186
_reference/reynolds/documentation/Rome Customer Update Specification 1.2.pdf.md Normal file
View File

@@ -0,0 +1,186 @@
# 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`)
```xml
<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)
```xml
<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
1. **Happy path**: valid `NameRecId`, minimal update → `StatusCode=0`.
2. **Record locked**: simulate concurrent change → `StatusCode=3`.
3. **No updates**: send no changing fields → `StatusCode=212`.
4. **Validation error**: bad phone/state/country combination → `StatusCode=202`.
5. **Customer missing**: bad `NameRecId` → `StatusCode=402`.
6. **Transport fault**: network/timeout; verify retry with same `BODId`.

216
_reference/reynolds/documentation/Rome Get Advisors Specification.pdf.md Normal file
View File

@@ -0,0 +1,216 @@
# Rome – Get Advisors (v1.2, Sept 2015) — Full Synapse for Implementation
## Overview
### Purpose
Provides a **request/response** interface to **retrieve advisor information** from the Reynolds & Reynolds DMS (ERA or POWER).
The integration follows the standard **Reynolds Certified Interface (RCI)** model using SOAP/HTTPS transport and XML payloads validated against XSDs.
### Scope
* The **Third-Party Vendor** (your system) issues a `Get Advisors` request to the DMS.
* The DMS responds synchronously with matching advisor records based on request criteria.
* Designed for **on-demand queries**, not for bulk advisor extractions.
---
## Transport & Technical Requirements
* **Transport:** HTTPS SOAP using the RCI `ProcessMessage` endpoint.
* **Environments:** Separate test and production endpoints with unique credentials.
* **Response Codes:** Standard HTTP responses per [RFC 2616 §10](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
* **Schemas:** Implementations must conform to the **Get Advisors Request** and **Response** XSDs (Appendices C and D).
---
## Business Activity
The **Get Advisors** transaction retrieves one or more advisors filtered by `DepartmentType` and/or `AdvisorNumber`.
Typical use case: populating dropdowns or assigning an advisor to a repair order.
Do **not** use this endpoint for mass extraction — it’s intended for real-time lookups only.
---
## Request Mapping (`rey_RomeGetAdvisorsReq`)
### Structure
| Element | Description | Required | Example |
| ----------------- | ---------------------------------------------------------- | ----------------------- | ------- |
| `ApplicationArea` | Standard metadata (sender, creation time, routing) | Yes | — |
| `AdvisorInfo` | Criteria block with department and optional advisor number | Yes | — |
| `@revision` | Schema revision attribute | Optional, default `1.0` | `1.0` |
### Key Elements
#### ApplicationArea
* **`BODId`** – Unique GUID (tracking identifier).
* **`CreationDateTime`** – `yyyy-MM-ddThh:mm:ssZ` (dealer local time).
* **`Sender.Component`** – `"Rome"`.
* **`Sender.Task`** – `"CU"`.
* **`Sender.ReferenceId`** – `"Query"`.
* **`Sender.CreatorNameCode`** – `"RCI"`.
* **`Sender.SenderNameCode`** – `"RCI"`.
* **`Destination.DestinationNameCode`** – `"RR"`.
* **`Destination.DealerNumber`** – 15-char DMS system ID (e.g. `123456789012345`).
* **`Destination.StoreNumber`** – 2-digit ERA or 6-digit POWER store code.
* **`Destination.AreaNumber`** – 2-digit ERA or 6-digit POWER branch code.
#### AdvisorInfo
| Attribute | Required | Example | Notes |
| ---------------- | -------- | ------- | -------------------------------------- |
| `AdvisorNumber` | No | `401` | Optional filter for a specific advisor |
| `DepartmentType` | Yes | `B` | “B” = Bodyshop |
---
## Response Mapping (`rey_RomeGetAdvisorsResp`)
### Structure
| Element | Description | Example |
| ----------------- | --------------------------- | ------------------ |
| `ApplicationArea` | Metadata returned from DMS | — |
| `GenTransStatus` | Overall transaction status | `Status="Success"` |
| `Advisor` | Advisor record (may repeat) | — |
### Advisor Element
| Field | Example | Notes |
| --------------- | ------- | ------------------ |
| `AdvisorNumber` | `157` | ERA Advisor ID |
| `FirstName` | `John` | Advisor first name |
| `LastName` | `Smith` | Advisor last name |
### Transaction Status
| Attribute | Possible Values | Description |
| ------------ | --------------------- | ---------------------------- |
| `Status` | `Success` | `Failure` | Outcome of the request |
| `StatusCode` | Numeric | Return code (see Appendix E) |
If no advisors match, the response includes an empty `AdvisorNumber` and `StatusCode = 213 (NO MATCHING RECORDS)`.
---
## Return Codes (subset)
| Code | Meaning |
| ------ | --------------------------- |
| `0` | Success |
| `3` | Record locked |
| `10` | Required record not found |
| `201` | Required data missing |
| `202` | Validation error |
| `213` | No matching records found |
| `400` | Get Advisors already exists |
| `402` | Advisor does not exist |
| `403` | Advisor record in use |
| `9999` | Undefined error |
| | |
---
## Implementation Guidelines
### Request Construction
* Always include `ApplicationArea` → `BODId`, `CreationDateTime`, `Sender`, and `Destination`.
* `DepartmentType` is **mandatory**.
* `AdvisorNumber` optional filter.
* Generate a new GUID per request.
* Match date/time to dealer local timezone.
### Response Handling
* Parse `GenTransStatus@Status` and `@StatusCode`.
* On success, map advisors into your system.
* On failure, use `StatusCode` and text node for error reporting.
* If no advisors found, handle gracefully with empty result list.
### Validation
* Validate outbound XML against `rey_RomeGetAdvisorsReq.xsd`.
* Validate inbound XML against `rey_RomeGetAdvisorsResp.xsd`.
---
## Example XMLs
### Request
```xml
<rey_RomeGetAdvisorsReq revision="1.0" xmlns="http://www.starstandards.org/STAR">
<ApplicationArea>
<BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
<CreationDateTime>2025-10-07T16:00:00Z</CreationDateTime>
<Sender>
<Component>Rome</Component>
<Task>CU</Task>
<ReferenceId>Query</ReferenceId>
<CreatorNameCode>RCI</CreatorNameCode>
<SenderNameCode>RCI</SenderNameCode>
</Sender>
<Destination>
<DestinationNameCode>RR</DestinationNameCode>
<DealerNumber>PPERASV02000000</DealerNumber>
<StoreNumber>05</StoreNumber>
<AreaNumber>03</AreaNumber>
</Destination>
</ApplicationArea>
<AdvisorInfo DepartmentType="B"/>
</rey_RomeGetAdvisorsReq>
```
### Response
```xml
<rey_RomeGetAdvisorsResp revision="1.0" xmlns="http://www.starstandards.org/STAR">
<ApplicationArea>
<BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
<CreationDateTime>2025-10-07T16:00:01Z</CreationDateTime>
<Sender>
<Component>Rome</Component>
<Task>CU</Task>
<ReferenceId>Update</ReferenceId>
<CreatorNameCode>RCI</CreatorNameCode>
<SenderNameCode>RCI</SenderNameCode>
</Sender>
<Destination>
<DestinationNameCode>RCI</DestinationNameCode>
<DealerNumber>PPERASV02000000</DealerNumber>
<StoreNumber>05</StoreNumber>
<AreaNumber>03</AreaNumber>
</Destination>
</ApplicationArea>
<GenTransStatus Status="Success" StatusCode="0"/>
<Advisor>
<AdvisorNumber>157</AdvisorNumber>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Advisor>
</rey_RomeGetAdvisorsResp>
```
---
## Integration Checklist for ImEX/Rome
* ✅ Map internal “Bodyshop Advisors” table → ERA Advisor IDs.
* ✅ Use `DepartmentType="B"` for bodyshop context.
* ✅ Cache responses short-term (e.g., 15 minutes) to minimize load.
* ✅ Log all `BODId` ↔ Status ↔ ReturnCode triplets for audit.
* ✅ Ensure XSD validation before and after transmission.
---

218
_reference/reynolds/documentation/Rome Get Part Specification.pdf.md Normal file
View File

@@ -0,0 +1,218 @@
# Rome – Get Part (v1.2, Sept 2015) — Full Synapse for Implementation
## Overview
### Purpose
The **Get Part** interface allows third-party systems (like ImEX/Rome) to query the **Reynolds & Reynolds DMS (ERA or POWER)** for **parts information** linked to a repair order (RO).
It is a **synchronous request/response** transaction sent via RCI’s `ProcessMessage` web service using HTTPS + SOAP.
---
## Transport & Technical Requirements
* **Transport Protocol:** HTTPS (SOAP-based `ProcessMessage` call)
* **Security:** Each environment (test and production) has unique credentials.
* **Response Codes:** Uses standard HTTP codes (per RFC 2616 §10).
* **Schemas:** Defined in Appendices C (Request) and D (Response) — validated XML.
* **Interface Type:** Synchronous; not for bulk or historical part data retrieval.
---
## Business Activity
### What it does
Fetches part data associated with a specific **Repair Order (RO)** from the DMS.
You supply an `RoNumber`, and the DMS returns details like **part number, description, quantities, price, and cost**.
### Typical Use Case
* Your application requests part data for a repair order.
* The DMS returns the current parts list for that RO.
### Limitation
⚠️ Not designed for mass extraction — one RO at a time only.
---
## Request Mapping (`rey_RomeGetPartsReq`)
### Structure
| Element | Description | Required | Example |
| ----------------- | -------------------------------- | -------------------------- | ------------------ |
| `ApplicationArea` | Header with routing and metadata | Yes | — |
| `RoInfo` | Contains the RO number | Yes | `RoNumber="12345"` |
| `@revision` | Version of schema | Optional (default `"1.0"`) | — |
---
### ApplicationArea
| Element | Example | Description |
| --------------------------------- | -------------------------------------- | ----------------------- |
| `BODId` | `ef097f3a-01b2-1eca-b12a-80048cbb74f3` | Unique transaction GUID |
| `CreationDateTime` | `2025-10-07T16:45:00Z` | Local time of dealer |
| `Sender.Component` | `"Rome"` | Sending application |
| `Sender.Task` | `"RCT"` | Literal |
| `Sender.ReferenceId` | `"Query"` | Literal |
| `Sender.CreatorNameCode` | `"RCI"` | Literal |
| `Sender.SenderNameCode` | `"RCI"` | Literal |
| `Destination.DestinationNameCode` | `"RR"` | Literal |
| `Destination.DealerNumber` | `PPERASV02000000` | DMS routing ID |
| `Destination.StoreNumber` | `05` | ERA store code |
| `Destination.AreaNumber` | `03` | ERA branch code |
---
### RoInfo
| Attribute | Required | Example | Description |
| ---------- | -------- | ------- | --------------------------------------------------- |
| `RoNumber` | Yes | `12345` | The repair order number for which to retrieve parts |
---
## Response Mapping (`rey_RomeGetPartsResp`)
### Structure
| Element | Description | Multiplicity |
| ----------------- | ---------------------------- | ------------ |
| `ApplicationArea` | Standard header | 1 |
| `GenTransStatus` | Transaction status block | 1 |
| `RoParts` | The returned parts record(s) | 1..N |
---
### RoParts Elements
| Element | Example | Description |
| ----------------- | ---------- | ---------------------------------------- |
| `PartNumber` | `FO12345` | Part number |
| `PartDescription` | `Gasket` | Description |
| `QuantityOrdered` | `2` | Quantity ordered |
| `QuantityShipped` | `2` | Quantity shipped |
| `Price` | `35.00` | Retail price |
| `Cost` | `25.00` | Dealer cost |
| `ProcessedFlag` | `Y` or `N` | Indicates whether part processed into RO |
| `AddOrDelete` | `A` or `D` | Whether the part was added or deleted |
> **Note:** A `ProcessedFlag` of `"N"` indicates a part was added via the API but not yet finalized in ERA Program 2525 (not sold). These parts are “echoed” back so the client does not mistake them for deleted ones.
---
## Transaction Status (`GenTransStatus`)
| Attribute | Possible Values | Example | Description |
| ------------ | -------------------- | ---------------------------- | ---------------------- |
| `Status` | `Success`, `Failure` | `"Success"` | Indicates outcome |
| `StatusCode` | Integer | `"0"` | Numeric status code |
| Text Node | Optional | `"No matching record found"` | Human-readable message |
---
## Return Codes (subset)
| Code | Meaning |
| ------ | ------------------------- |
| `0` | Success |
| `3` | Record locked |
| `10` | Required record not found |
| `201` | Required data missing |
| `202` | Validation error |
| `519` | No part available |
| `9999` | Undefined error |
---
## Example XMLs
### Request
```xml
<rey_RomeGetPartsReq revision="1.0" xmlns="http://www.starstandards.org/STAR">
<ApplicationArea>
<BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
<CreationDateTime>2025-10-07T16:00:00Z</CreationDateTime>
<Sender>
<Component>Rome</Component>
<Task>RCT</Task>
<ReferenceId>Query</ReferenceId>
<CreatorNameCode>RCI</CreatorNameCode>
<SenderNameCode>RCI</SenderNameCode>
</Sender>
<Destination>
<DestinationNameCode>RR</DestinationNameCode>
<DealerNumber>PPERASV02000000</DealerNumber>
<StoreNumber>05</StoreNumber>
<AreaNumber>03</AreaNumber>
</Destination>
</ApplicationArea>
<RoInfo RoNumber="12345"/>
</rey_RomeGetPartsReq>
```
### Response
```xml
<rey_RomeGetPartsResp revision="1.0" xmlns="http://www.starstandards.org/STAR">
<ApplicationArea>
<BODId>ef097f3a-01b2-1eca-b12a-80048cbb74f3</BODId>
<CreationDateTime>2025-10-07T16:00:01Z</CreationDateTime>
<Sender>
<Component>RCT</Component>
<Task>RCT</Task>
<ReferenceId>Update</ReferenceId>
<CreatorNameCode>RCI</CreatorNameCode>
<SenderNameCode>RCI</SenderNameCode>
</Sender>
<Destination>
<DestinationNameCode>RR</DestinationNameCode>
<DealerNumber>PPERASV02000000</DealerNumber>
<StoreNumber>05</StoreNumber>
<AreaNumber>03</AreaNumber>
</Destination>
</ApplicationArea>
<GenTransStatus Status="Success" StatusCode="0"/>
<RoParts>
<PartNumber>FO12345</PartNumber>
<PartDescription>Gasket</PartDescription>
<QuantityOrdered>2</QuantityOrdered>
<QuantityShipped>2</QuantityShipped>
<Price>35.00</Price>
<Cost>25.00</Cost>
<ProcessedFlag>Y</ProcessedFlag>
<AddOrDelete>A</AddOrDelete>
</RoParts>
</rey_RomeGetPartsResp>
```
---
## Implementation Notes for ImEX/Rome
✅ **Request**
* Always include `RoNumber`.
* `BODId` must be a unique GUID.
* Set correct DMS routing (dealer/store/branch).
* Validate against XSD before sending.
✅ **Response**
* Parse `GenTransStatus.Status` and `StatusCode`.
* If `519` (no part available), handle gracefully.
* `ProcessedFlag="N"` parts should not be treated as active.
* Cache parts data locally for quick access.
✅ **Error Handling**
* Log `BODId`, `StatusCode`, and XML payloads.
* Retry transient network errors; not logical ones (e.g., 519, 10).
---

84
_reference/reynolds/documentation/Rome Insert Service Vehicle Interface Specification.pdf.md Normal file
View File

@@ -0,0 +1,84 @@
## 🧩 **Rome Service Vehicle Insert — Developer Integration Summary**
### **Purpose & Scope**
This interface allows third-party systems (like your Rome middleware) to insert a new *Service Vehicle* record into the Reynolds & Reynolds DMS.
The DMS will validate the provided vehicle and customer data, create the record if valid, and respond with a status of `Success` or `Failure`.
---
### **Core Workflow**
1. **POST** a SOAP request to the Reynolds endpoint (`ProcessMessage`).
2. Include the XML payload structured as `rey_RomeServVehicleInsertRequest`.
3. Receive `rey_RomeServVehicleInsertResponse` with:
* Transmission status (`GenTransStatus`),
* Optional `StatusCode` from the return codes table (Appendix E).
---
### **Request (`rey_RomeServVehicleInsertRequest`)**
**Sections:**
* **ApplicationArea**
* Metadata such as `CreationDateTime`, `BODId`, and sender/destination details.
* **Vehicle**
* Basic vehicle identity fields (`Vin`, `VehicleMake`, `VehicleYear`, etc.).
* Sub-element `VehicleDetail` for mechanical attributes (`Aircond`, `EngineConfig`, etc.).
* **VehicleServInfo**
* Operational context: stock ID, customer number, advisor, warranty, production dates, etc.
* Includes sub-elements:
* `VehExtWarranty` (contract #, expiration date/mileage)
* `Advisor` → `ContactInfo` (NameRecId)
**Required core fields**
* `Vin` (validated via `GEVINVAL`)
* `VehicleMake`, `VehicleYear`, `ModelDesc`, `Carline`
* `CustomerNo` (must pre-exist)
* `SalesmanNo` (valid advisor)
* `InServiceDate` ≤ current date
* `TeamCode` – must exist in `MECHANICS` file
---
### **Response (`rey_RomeServVehicleInsertResponse`)**
**Elements:**
* `ApplicationArea` – mirrors request metadata.
* `GenTransStatus` – attributes:
* `Status` = `Success` | `Failure`
* `StatusCode` = numeric code (see Appendix E)
---
### **Error Codes (Appendix E Highlights)**
| Code | Meaning |
| ------ | ----------------------------------------------------- |
| `0` | Success |
| `300` | Vehicle already exists |
| `301` | Invalid make or ownership not established |
| `502` | Advisor was terminated |
| `506` | Mileage must be greater than last mileage |
| `513` | VIN must be added to ERA2 before an RO can be created |
| `9999` | Undefined error |
---
### **Implementation Notes**
* Endpoint authentication and URL differ between **test** and **production**.
* Ensure all date fields follow format `MM/DD/YYYYThh:mm:ssZ(EST)` (local dealer time).
* Use `GUID` for `BODId` to ensure message traceability.
* Validate VIN before submission; rejected VINs halt insertion.
---

59
_reference/reynolds/documentation/Rome Search Customer Service Vehicle Combined Specification.pdf.md Normal file
View File

@@ -0,0 +1,59 @@
# Rome – Search Customer Service Vehicle Combined (v1.1, May 2015) — Full Synapse
**What it does:** one-shot search that returns **customer identity + all matching service vehicles** based on exactly **one** of the permitted search patterns (e.g., `NameRecId`, `FullName`, `Phone`, `Partial VIN`, `Stock #`, `License #`, or `FullName/LName + Model triple`). Results include customer contact info and each vehicle’s details and service metadata.
## Transport
* **SOAP/HTTPS** to RCI `ProcessMessage`, separate **test** and **prod** endpoints/credentials.
* Standard HTTP response codes; XML payloads validate against request/response XSDs.
## Trigger & allowed search modes
Pick **exactly one** of these (no mixing):
1. `Last Name + Partial VIN`
2. `Full Name + Partial VIN`
3. `Last Name + Phone`
4. `Full Name + Phone`
5. `Full Name` (alone)
6. `NameRecId` (alone)
7. `Phone` (alone)
8. `Phone + Partial VIN`
9. `Last Name + (Make, Model, Year)`
10. `Full Name + (Make, Model, Year)`
11. `Vehicle Stock #` (alone)
12. `Vehicle License #` (alone)
13. `Partial or Full VIN` (alone)
Business customers only match with `NameRecId`, `Phone`, `Stock #`, `License #`, `Phone+Partial VIN`, or `Partial/Full VIN`.
## Request (`rey_RomeCustServVehCombReq`)
* **`ApplicationArea`**: `Sender` (Component=`Rome`, Task=`CVC`, CreatorNameCode=`RCI`, SenderNameCode=`RCI`), `CreationDateTime` (`yyyy-mm-ddThh:mm:ssZ`), optional `BODId` (GUID), `Destination` (DestinationNameCode=`RR`, plus dealer/store/area routing).
* **`CustServVehCombReq`**:
* `QueryData`: one of `LName`, `FullName(FName,LName,MName)`, `NameRecId(CustIdStart)`, `Phone(Num)`, `PartVIN(Vin)`, `StkNo(VehId)`, `LicenseNum(LicNo)`; optional `MaxRecs` (≤ 50).
* `VehData`: `MakePfx` (2-char make), `Model` (carline/description match), `Year` (2 or 4).
* `OtherCriteria` present but “not used”.
## Response (`rey_RomeCustServVehComb`)
* **`ApplicationArea`** (Sender typically `RR`, Task=`CVC`, etc.) and **`TransStatus`** with `Status`=`Success|Failure`, `StatusCode` (numeric), and optional message text.
* **`CustServVehComb`** records (0..n), each with:
* **`NameContactId`**: `NameId` (`IBFlag` `I|B`, individual or business name + optional `NameRecId`), plus repeating `Address`, `ContactOptions`, `Phone`, `Email`.
* **`ServVehicle`** (0..n): `Vehicle` (VIN, Make, Year, Model, Carline, color, detail attrs), and `VehicleServInfo` (attributes for StockID, CustomerNo, Service history fields; children: `VehExtWarranty`, `Advisor.ContactInfo@NameRecId`, `VehServComments*`).
## Return codes (subset)
* `0` Success; `201` Required data missing; `202` Validation error; `213` No matching records; `9999` Undefined error. (Use `TransStatus@StatusCode` + text to decide UX.)
## Implementation checklist
* Build one of the **allowed** queries; if multiple criteria are supplied, RCI treats it as invalid.
* Generate **`BODId`** GUID per call; log it for tracing.
* Fill **routing** (`DealerNumber`, `StoreNumber`, `AreaNumber`) for the target store/branch.
* Enforce `MaxRecs` (default is 1; if >1 results and `MaxRecs` omitted, API returns “multiple exist” error).
* XSD-validate request/response; map `TransStatus` to domain errors; return empty list on `213`.
---

76
_reference/reynolds/documentation/Rome Update Body Shop Management Repair Order Interface Specification.pdf.md Normal file
View File

@@ -0,0 +1,76 @@
# Rome – Update Body Shop Management Repair Order (v1.6, Jan 2016) — Full Synapse
**Purpose**
This interface allows a Body Shop Management (BSM) system to update an existing *Repair Order (RO)* in the Reynolds & Reynolds DMS. It covers updates to general RO details, labor operations, parts, GOG (gas, oil, grease) items, and miscellaneous charges .
---
## 🧩 Core Workflow
1. **BSM System → RCI Gateway → Reynolds DMS**
* BSM sends a SOAP/XML request (`rey_RomeUpdateBSMRepairOrderReq`) to RCI.
* DMS validates and processes the update.
* DMS replies with `rey_RomeUpdateBSMRepairOrderResp`.
2. **Supported updates**
* Comments, tax codes, and estimate type.
* Labor operation details (e.g., billing rates, opcodes).
* Parts (add, delete, modify).
* GOG and Misc items with financial attributes.
---
## 🧱 Request Structure — `rey_RomeUpdateBSMRepairOrderReq`
| Section | Description | |
| ------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **ApplicationArea** | Identifies sender (`Rome/RCI`), creation time, and destination dealer/store. | |
| **RoRecord** | Main data payload, with attribute `FinalUpdate="Y | N"`. Includes general, labor, part, GOG, and misc subsections. |
### RoRecord subsections
* **Rogen:** Header data — `RoNo`, `CustNo`, `TagNo`, mileage, and optional `RoCommentInfo`, `EstimateInfo`, and `TaxCodeInfo`.
* **Rolabor:** One or more `OpCodeLaborInfo` nodes containing:
* `OpCode`, `JobNo`, and pay type flags (`Cust`, `Intr`, `Warr`).
* Nested `BillTimeRateHrs`, `CCCStmts` (Cause/Complaint/Correction), and `RoAmts` (billing amounts).
* **Ropart:** Job-linked `PartInfoByJob` with `OSDPartDetail` items.
* **Rogog:** “Gas/Oil/Grease” lines (`AllGogOpCodeInfo` → `AllGogLineItmInfo`).
* **Romisc:** Miscellaneous charge sections (`MiscOpCodeInfo` → `MiscLineItmInfo`).
---
## 📤 Response Structure — `rey_RomeUpdateBSMRepairOrderResp`
| Element | Description | |
| ------------------- | ---------------------------------------------------------------------------------------- | --------------------------------- |
| **ApplicationArea** | Mirrors the request metadata (sender now `ERA/RR`). | |
| **GenTransStatus** | `Status="Success | Failure"`and numeric`StatusCode`. |
| **RoRecordStatus** | Attributes include `Status`, `Date`, `Time`, `OutsdRoNo`, `DMSRoNo`, and `ErrorMessage`. | |
---
## ⚙️ Key Return Codes
| Code | Meaning |
| ------ | ---------------------- |
| `0` | Success |
| `300` | RO not found |
| `301` | Invalid RO number |
| `501` | Invalid tax code |
| `503` | Invalid opcode |
| `9999` | Undefined system error |
---
## 🧩 Implementation Notes
* **FinalUpdate="Y"** signals the RO is finalized in the DMS.
* The DMS uses **RO#, Dealer#, and Store#** to locate the target record.
* **JobNo** groups labor and parts within the same operation.
* Monetary and tax fields are sent as strings (DMS expects implicit decimal).
* Every RO update must be uniquely identified by a **BODId** (GUID).
* Validation failures trigger a response with `Status="Failure"` and `ErrorMessage` populated.

6
server/rr/rr-job-export.js
View File

@@ -262,7 +262,7 @@ const updateRRRepairOrderWithFullData = async (args) => {
CreateRRLogEvent(socket, "INFO", "RR allocations resolved for update", {
hasAllocations: allocations.length > 0,
count: allocations.length,
allocationsPreview: allocations.slice(0, 2).map(a => ({
allocationsPreview: allocations.slice(0, 2).map((a) => ({
type: a?.type,
code: a?.code,
laborSale: a?.laborSale,
@@ -322,11 +322,11 @@ const updateRRRepairOrderWithFullData = async (args) => {
// Add roNo for linking to existing RO
payload.roNo = String(roNo);
payload.outsdRoNo = job?.ro_number || job?.id || undefined;
// Keep rolabor - it's needed to register the job/OpCode accounts in Reynolds
// Without this, Reynolds won't recognize the OpCode when we send rogg operations
// The rolabor section tells Reynolds "these jobs exist" even with minimal data
CreateRRLogEvent(socket, "INFO", "Sending full data for early RO (using create with roNo)", {
roNo: String(roNo),
hasRolabor: !!payload.rolabor,

173
server/rr/rr-job-helpers.js
View File

@@ -52,6 +52,122 @@ const asN2 = (dineroLike) => {
return amount.toFixed(2);
};
/**
* Normalize various "money-like" shapes to integer cents.
* Supports:
* - Dinero instances (getAmount / toUnit)
* - { cents }
* - { amount, precision }
* - plain numbers (treated as units, e.g. dollars)
* - numeric strings (treated as units, e.g. "123.45")
* @param value
* @returns {number}
*/
const toMoneyCents = (value) => {
if (value == null || value === "") return 0;
if (typeof value.getAmount === "function") {
return value.getAmount();
}
if (typeof value.toUnit === "function") {
const unit = value.toUnit();
return Number.isFinite(unit) ? Math.round(unit * 100) : 0;
}
if (typeof value.cents === "number") {
return value.cents;
}
if (typeof value.amount === "number") {
const precision = typeof value.precision === "number" ? value.precision : 2;
if (precision === 2) return value.amount;
const factor = Math.pow(10, 2 - precision);
return Math.round(value.amount * factor);
}
if (typeof value === "number") {
return Math.round(value * 100);
}
if (typeof value === "string") {
const parsed = Number.parseFloat(value);
return Number.isFinite(parsed) ? Math.round(parsed * 100) : 0;
}
return 0;
};
const asN2FromCents = (cents) => asN2({ amount: Number.isFinite(cents) ? cents : 0, precision: 2 });
/**
* Build RR estimate block from allocation totals.
* @param {Array} allocations
* @returns {{parts: string, labor: string, total: string}|null}
*/
const buildEstimateFromAllocations = (allocations) => {
if (!Array.isArray(allocations) || allocations.length === 0) return null;
const totals = allocations.reduce(
(acc, alloc) => {
acc.parts += toMoneyCents(alloc?.partsSale);
acc.labor += toMoneyCents(alloc?.laborTaxableSale);
acc.labor += toMoneyCents(alloc?.laborNonTaxableSale);
acc.total += toMoneyCents(alloc?.totalSale);
return acc;
},
{ parts: 0, labor: 0, total: 0 }
);
// If totalSale wasn't provided, keep total coherent with parts + labor.
if (!totals.total) {
totals.total = totals.parts + totals.labor;
}
return {
parts: asN2FromCents(totals.parts),
labor: asN2FromCents(totals.labor),
total: asN2FromCents(totals.total)
};
};
/**
* Build RR estimate block from precomputed job totals.
* @param job
* @returns {{parts: string, labor: string, total: string}|null}
*/
const buildEstimateFromJobTotals = (job) => {
const totals = job?.job_totals;
if (!totals) return null;
const partsCents = toMoneyCents(totals?.parts?.parts?.total) + toMoneyCents(totals?.parts?.sublets?.total);
const laborCents = toMoneyCents(totals?.rates?.rates_subtotal ?? totals?.rates?.subtotal);
let totalCents = toMoneyCents(totals?.totals?.subtotal);
if (!totalCents) {
totalCents = partsCents + laborCents;
}
// If we truly have no numbers from totals, omit estimate entirely.
if (!partsCents && !laborCents && !totalCents) return null;
return {
parts: asN2FromCents(partsCents),
labor: asN2FromCents(laborCents),
total: asN2FromCents(totalCents)
};
};
/**
* Build RR estimate block from the best available source.
* @param job
* @param allocations
* @returns {{parts: string, labor: string, total: string}|null}
*/
const buildRREstimate = ({ job, allocations } = {}) => {
return buildEstimateFromAllocations(allocations) || buildEstimateFromJobTotals(job);
};
/**
* Build RO.GOG structure for the reynolds-rome-client `createRepairOrder` payload
* from allocations.
@@ -103,44 +219,6 @@ const buildRogogFromAllocations = (allocations, { opCode, payType = "Cust", roNo
const ops = [];
/**
* Normalize various "money-like" shapes to integer cents.
* Supports:
* - Dinero instances (getAmount / toUnit)
* - { cents }
* - { amount, precision }
* - plain numbers (treated as units, e.g. dollars)
*/
const toCents = (value) => {
if (!value) return 0;
if (typeof value.getAmount === "function") {
return value.getAmount();
}
if (typeof value.toUnit === "function") {
const unit = value.toUnit();
return Number.isFinite(unit) ? Math.round(unit * 100) : 0;
}
if (typeof value.cents === "number") {
return value.cents;
}
if (typeof value.amount === "number") {
const precision = typeof value.precision === "number" ? value.precision : 2;
if (precision === 2) return value.amount;
const factor = Math.pow(10, 2 - precision);
return Math.round(value.amount * factor);
}
if (typeof value === "number") {
return Math.round(value * 100);
}
return 0;
};
const asMoneyLike = (amountCents) => ({
amount: amountCents || 0,
precision: 2
@@ -154,13 +232,13 @@ const buildRogogFromAllocations = (allocations, { opCode, payType = "Cust", roNo
// Only centers configured for RR GOG are included
if (!breakOut || !itemType) continue;
const partsTaxableCents = toCents(alloc.partsTaxableSale);
const partsNonTaxableCents = toCents(alloc.partsNonTaxableSale);
const extrasTaxableCents = toCents(alloc.extrasTaxableSale);
const extrasNonTaxableCents = toCents(alloc.extrasNonTaxableSale);
const laborTaxableCents = toCents(alloc.laborTaxableSale);
const laborNonTaxableCents = toCents(alloc.laborNonTaxableSale);
const costCents = toCents(alloc.cost);
const partsTaxableCents = toMoneyCents(alloc.partsTaxableSale);
const partsNonTaxableCents = toMoneyCents(alloc.partsNonTaxableSale);
const extrasTaxableCents = toMoneyCents(alloc.extrasTaxableSale);
const extrasNonTaxableCents = toMoneyCents(alloc.extrasNonTaxableSale);
const laborTaxableCents = toMoneyCents(alloc.laborTaxableSale);
const laborNonTaxableCents = toMoneyCents(alloc.laborNonTaxableSale);
const costCents = toMoneyCents(alloc.cost);
const segments = [];
@@ -418,6 +496,11 @@ const buildRRRepairOrderPayload = ({
mileageIn: job.kmin
};
const estimate = buildRREstimate({ job, allocations });
if (estimate) {
payload.estimate = estimate;
}
if (story) {
payload.roComment = String(story).trim();
}