bodyshop/_reference/reynolds/documentation/Rome Get Advisors Specification.pdf.md

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

<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

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

---