219 lines
8.1 KiB
Markdown
219 lines
8.1 KiB
Markdown
# 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).
|
||
|
||
---
|