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

---