hotfix/2026-02-27 - Reynolds Estimate amounts on second call, + RR Docs in _ref
This commit is contained in:
Dave
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user