bodyshop/_reference/reynolds/documentation/Rome Customer Insert Specification 1.2.pdf.md

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

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