Oracle® Retail POS Suite Implementation Guide, Volume 1 – Implementation Solutions Release 14.1 E54475-02 |
|
Previous |
Next |
This chapter provides information on implementing Returns Management. It covers the following topics:
Oracle Retail Returns Management is a centralized system designed to monitor and control the return of retail merchandise. Control is provided through a flexible set of rules that determine if a particular item is returnable. Monitoring is provided through pattern watches, enabling a retailer to uncover unusual return patterns indicative of fraud, poor product quality, and so on.
At its most basic, Returns Management enables you to centralize the knowledge and decision making of what is and what is not returnable.
Returns Management is packaged as a standalone product.
Returns Management provides:
A flexible and configurable set of rules
The ability to collect differing rules into multiple policies
The ability to assign different policies to different situations (for instance, one policy might apply to receipted items, another policy might apply to non-receipted items)
A decision engine to initiate the policies
A defined application-program interface (API) for evaluation of returnability
A defined API for post-return information gathering
A web-based user interface for administration
Occasionally, a customer might buy an item from a retailer and then decide that they no longer want the item. This could be for any number of reasons:
Dissatisfaction with quality
Finding a better price somewhere else
Buying the wrong size
Most retailers allow customers to return items they have purchased under certain conditions. Conditions might include that the item was bought within the last 90 days, that the item is in an unopened state, or that the customer has a receipt. Additionally, a retailer might decide to charge a restocking fee, issue a return merchandise authorization (RMA) and a call tag, provide a discount on the customer's next purchase (in case of a quality problem), or other actions based around the return. Finally, returns can happen at different places in a retailer, such as at a point-of-sale, a separate returns desk, or at a remote call center.
With the act of returning, there are several steps that a retailer must go through.
A retailer must determine what merchandise is being returned.
A retailer must decide if the merchandise is returnable.
A retailer must record that the item was returned, which affects financial and inventory calculations.
Once the retailer accepts a return, the retailer must physically move the item to some place (such as placing it in a returns cage, or issuing pickup instructions to a carrier in the case of a remote call center). Afterwards, the item might undergo further actions, such as being returned to the vendor or destroyed.
Of these many aspects of the return process, Returns Management focuses mainly on the conditions for return, sometimes referred to in this document as returnability. Returnability is determined by the rules and policies configured in Returns Management. Returns Management can associate metadata with return policies so Returns Management can decide to use different policies in different situations. Each policy has its own set of rules which define returnability for that situation, for example, non-receipted returns might be more restrictive than receipted returns.
A policy is composed of one or more rules. Each policy has associated metadata that enables the service layer to choose the most appropriate policy for the current item in question.
Returns Management does not prescribe for the point-of-return, what happens before or after a customer initiates a return, or the financial and inventory ramifications of the returns process. Furthermore, Returns Management isolates itself from the majority of data found in the retail enterprise and restricts itself to knowing a prescribed set of facts. It is this set of facts that Returns Management uses when evaluating a policy and determining if a product is returnable.
Returns Management has been isolated to this degree in order to make Returns Management applicable to a wide variety of situations. As long as a point-of-return can communicate with Returns Management, it is immaterial where that point-of-return is located and what kind of point-of-return it is (register, returns desk, and so forth). The point-of-return provides the majority of the data that Returns Management needs to make its decision, so Returns Management is shielded from the format of transaction data in a retail enterprise.
By configuring the rules and policies in Returns Management, the retailer can enforce the same return policies across the enterprise. The return policies can be centrally administered. Since the policies are not compiled code, they can be quickly updated. Finally, Returns Management records the steps it makes for each decision, allowing a customer to ask exactly why a return was accepted or declined.
As stated previously, Returns Management focuses mainly on the conditions for return. The other main focus of Returns Management is that it keeps a record of what was actually returned to the enterprise. This information is rolled up in both the return ticket data (there is a ticket for each return, each ticket having one or more line items corresponding to items on the return) as well as a list of exception activity. The exception file records unusual activity that might be fraudulent. Using these records, Returns Management provides decision support to the enterprise. The retail enterprise can monitor these records to determine the volume of returns, the type of items being returned, and patterns of fraudulent behavior.
Figure 9-2 identifies how Returns Management exists with other existing Oracle Retail products. Also included in the context are the actors mentioned in Table 9-1.
Table 9-1 lists the actors that Returns Management expects to interact with, and their interactions. Although most of the actors are users, some items, such as the point-of-return, are expected to interact with Returns Management without direct human intervention.
Table 9-1 Oracle Retail Returns Management Actors
STORE | CORPORATE | |||||||
---|---|---|---|---|---|---|---|---|
Sales Associate | Point-of-return | Store Manager | Business analyst | Customer Service Rep | Loss Prevention Specialist | Software Developer | ||
Request return |
X |
NA |
NA |
NA |
NA |
X |
NA |
NA |
Update return information |
NA |
X |
NA |
NA |
NA |
NA |
NA |
NA |
Develop return policies |
NA |
NA |
NA |
NA |
X |
NA |
NA |
X |
Monitor exception behaviors |
NA |
NA |
X |
NA |
NA |
NA |
X |
NA |
Monitor what is being returned |
NA |
NA |
X |
NA |
X |
NA |
X |
NA |
Audit a specific returns decision |
NA |
NA |
NA |
NA |
X |
X |
NA |
NA |
Returns Management evaluates data provided from the point-of-return as well as centrally stored historical data and provides a recommendation to the point-of-return for the handling of a potential return. Because Returns Management is not transactional in nature, Returns Management has no tax responsibility. All of the tax responsibility belongs to the point-of-return when the return transaction is created and processed.
Note: Returns Management operates using a single default currency. If operations require using multiple currencies, it is the responsibility of the point-of-return to convert from any other currencies to the single default currency being used by the system. Returns Management does not provide services for the conversion of currency from one form to another. |
This chapter addresses the functional aspects of Returns Management and provides the following:
Figure 9-3 illustrates the steps in a typical Returns Management session, including which steps are initiated by Returns Management and which steps are initiated by the point-of-return (the point at which a return is initiated, for example, a cashier at a retailer).
Note: This flowchart is a simplified representation of the service flow and does not attempt to explain the technologies used to implement Returns Management. |
The following sequence is a typical Returns Management round-trip session:
A point-of-return initiates a merchandise return.
A message is sent from the point-of-return to the Returns Management system indicating the item to be returned, if the customer has a receipt, and possibly other data. See "Point-of-Return to Returns Management—Initial Return Request".
Returns Management chooses which policy to initiate. A policy is comprised of one or more rules, and each policy has associated metadata that enables the service layer to choose the most appropriate policy for the current item in question. See the Oracle Retail Returns Management User Guide.
Returns Management gathers together relevant server-side historical information, such as entries related to the customer in the exception file.
The policy might require additional data from the point-of-return, such as a positive ID from the customer. In this case, a message is sent back to the point-of-return asking for the additional data. See "Returns Management to Point-of-Return—Initial Return Response: Need Positive ID".
The policy decides if the item is returnable or not. Returns Management informs the point-of-return of its decision, and provides a tender recommendation.
The point-of-return ultimately decides to accept the return or not. For example, Returns Management might say that an item is non-returnable, but a local manager might override that decision. A local manager can also ignore a tender recommendation.
The point-of-return informs Returns Management of its decision. See "Point-of-Return to Returns Management—Return Result from Second Response".
Returns Management uses information from the point-of-return to update its historical records such as the exception file. The exception file acts as a constantly evolving knowledge base that can help the analytic engine decide which customers, items, cashiers, or stores are at higher risk for return fraud.
To understand how the various modules relate to each other at run time, imagine the flow of data through the system.
The four main processes (return request, return results, policy administration, and auditing) operate on an intersecting set of data.
Return requests are sent to Returns Management and cause return tickets to be created and rules to be read.
Rule initiation creates entries in the audit log.
Return responses are sent back to the point-of-return.
Return results update existing return tickets, and create entries in the exception file.
Policy administration enables the creation and maintenance of policies. See the Oracle Retail Returns Management User Guide.
Auditing applications read the audit entries created during the evaluation phase.
shows the four main processes and the flow of the data that they create and consume.
Note: The Rules and Policy Maintenance interface is shown as directly updating the policy rules using Create, Read, Update, Delete (CRUD). |
Though Returns Management needs to be informed of returns performed, it is not a requirement that the point-of-return itself informs Returns Management. This means that this information can be conveyed by a separate process, such as a scheduled transaction parsing routine. This also means that the point-of-return does not need to have direct access to the process final result API of Returns Management.
The historical data read by Returns Management at the beginning of a return request is the data that is updated by the return information delivered after a successful return.
The historical data recorded by Returns Management is not the same as purely transactional data, for example, POSLog. The historical data is data that reflects inferred customer behavior, such as too many returns over a specified amount of time.
The retail transaction data is read by the point-of-return, not by Returns Management.
The following are different functional overviews.
Return tickets enable an operator to inquire about the particulars of a specific return approval or denial. A return ticket is any attempt by a customer to return one or more items, from one or more originating transactions or from no identifiable transaction. The return ticket carries a unique identifier that can consist of the store number and workstation ID from which the return attempt occurs, an eight-digit date in MMDD-YYYY format, and sequence number. The operator can search for a return ticket by the unique identifier or other information, such as cashier, customer, or item information.
The operator can be a loss prevention operator researching potentially fraudulent return activity, or a customer service person researching why a particular customer's return was denied.
The Returns Management exception file is created and maintained by Returns Management for use in detecting and preventing fraud at the point-of-return. The exception file acts as a constantly evolving knowledge base that can help the authorization engine decide which customers or cashiers are at higher risk for return fraud.
Exceptions are instances of a behavior that a retailer has selected to track for a customer or cashier. The exception file holds an exception counter for a customer; the exception counter is incremented based on suspicious return activity. If a return activity is selected for inclusion in the exception counter, the system increments the exception count for each suspicious shopping activity. Likewise, return activities can be configured for cashiers.
When an exception occurs, a record is written to the exception file and the activity is available for research on that customer or cashier using the exception inquiry search and display screens. All exceptions are based on return ticket data.
Exception counts are based on real-time refund attempt activities occurring at the point-of-return, using the return result message that is sent by the point-of-return to Returns Management at the conclusion of a transaction with an attempted refund. Return activities include activities that increment counters such as a return transaction by the customer without a receipt and with no retrieval of the original transaction, five same-day returns as purchases within the last three days, and three returns today. In turn, normal activity levels might be exceeded and counting generated based on those counters.
The message and response component of Returns Management includes the messages sent from the point-of-return that might trigger action in Returns Management and an appropriate response message. Returns Management communicates with brick and mortar, e-commerce, and call center point-of-return environments using a messaging interface to receive return authorization requests, use retailer-defined return policies to determine authorization or denial of items and valid return tenders, and respond with the applicable approval or denial code.
A return policy consists of multiple rules that ask a question about an attempted return. The retailer sets the order in which the rules are evaluated upon a return. The retailer determines the action to take based on the answer to the question. The action taken based on the answer to the question is:
Continue
Continue At Rule Number
Stop Processing
The following is an overview of the analytic engine.
A return policy consists of multiple rules that ask a question about an attempted return, such as some of the following:
Does the customer have a receipt?
Is the item serialized?
Does the serial number on the item being returned match the serial number of the item as originally purchased?
What is the customer's cumulative exception count?
What is the condition of the item?
The retailer sets the order in which the rules are evaluated upon a return.
The retailer determines through the front end the action to take based on the answers to the questions.
The answer can be Yes or No (Boolean), a certain numeric or currency number (Range), or one possible response from a valid list of responses (Discrete), based on the type of question being asked. For example, "Does the customer have a receipt?" has a Yes or No response. "What is the customer's cumulative exception count?" has a numeric response that would fall within a range configured by the retailer. "What is the condition of the item?" maps to a response chosen by the point-of-return operator, such as one of the following:
Excellent
Good
Fair
Poor
Open Box
Damaged
Used
The analytic engine uses one of these items to decide returnability.
The action taken based on the answer to the question is one of the following:
Continue—Check the next rule within the policy.
Continue At Rule Number—Check a particular rule within the policy and then continue.
Stop Processing—Do not continue checking rules. Processing complete.
The retailer can set a configurable response code to be returned with every action. Response codes consist of a required positive numeric code, response type, response priority within that type, short description, and an optional long description that can be used for scripting customer service responses to customer inquiries. The response type for each response code is selected from the following, which are listed in priority order:
Denial.
Manager Overridden Denial—The engine has denied the item but the denial can be overridden at the point-of-return by a properly authorized user.
Contingent Authorization—The engine has approved the item contingent upon capture of an override at the point-of-return by a properly authorized user.
Authorization.
Response codes are prioritized within response types. No two response codes of the same response type can have the same priority. As the analytic engine evaluates policy rules, the system holds the highest priority response code within that response type as the response, until a rule resulting in a higher response type, with a higher priority, supersedes it, thus the retailer can control whether the most favorable or least favorable response is returned to the point-of-return.
The retailer also determines the tenders that are enabled for a return. When the response is Continue or Continue At Rule Number, the tenders set for the rule carry forward until they are superseded by the response to a following rule. If there is no following rule that must be evaluated, then the tenders collected as a response to that rule are the available tenders that are returned to the point-of-return in the response message.
An indicator can be set on a policy rule response that indicates positive ID is required in order to check this rule, and the policy cannot be evaluated unless the positive ID is obtained and the exception file checked. In this case, an additional call to Returns Management is made, for another evaluation once customer positive ID is obtained.
The collection of rules (policy) is assigned to a combination of location (node of the store reporting hierarchy, ad hoc store groups, or individual stores) and items, which can be designated by item or merchandise hierarchy. When a return is attempted at a point-of-return, the system determines the appropriate policy to apply based on the item being returned and the store where the return is being performed. The item designation supersedes the store designation in the case where two policies might otherwise be equivalent.
Two default policies must be defined for the analytic engine to use:
Receipted items
Non-receipted items
Exception policies can then be set to cover specific items, such as serialized items that include warranties, or articles of clothing that cannot be returned under any condition. When the system does not find a policy applying specifically to the line item being returned, the system falls back to the appropriate default receipted or non-receipted policy to evaluate returnability.
When the returnability has been determined based on the appropriate policy, the system checks for any other items that the customer is attempting to return at that time. When the responses have been determined for all items in the attempted return, the system sends the return response message with the evaluation results for the attempted return. The response for an attempted line item return includes a response code and description that are determined by the retailer.
The point-of-return can then use the response information to control flow to complete the return, such as prompting for a manager override, presenting the enabled tenders, or displaying information for why a return is not allowed.
Customer service overrides are granted to a customer using the Customer Exception Details screen. The presence of a customer service override for a particular positive ID is checked at the end of return engine evaluation if any line item evaluates to a Manager Overridden Denial, or Denial. Customer service overrides are associated and used with a return ticket. If the return ticket is subsequently voided, the customer service override is considered unused and might be used with a subsequent return authorization. If more than one customer service override exists, the system applies them to the return in order from oldest to newest, by date.
Customer service overrides can consist of more than one allowed return within an override. The Max Customer Service Overrides parameter limits the number of allowed returns within the override and the total number of overrides granted to a customer.
The main integration point of Returns Management is with an external point-of-return. To communicate between the systems, Returns Management provides methods which accept and return messages in a predefined format. This chapter discusses the methods and the messages. This chapter also discusses some of the implications of the chosen implementations.
Returns Management has two primary methods of contact with the point-of-return:
The point-of-return requests return authorization from Returns Management (evaluation).
The point-of-return notifies Returns Management of what was actually returned (exception tracking).
Both of these methods use XML messages. The call to evaluation is a synchronous call that returns a separate XML message. The call to scoring is an asynchronous call.
The three messages defined by Returns Management are:
Return Authorization Request
Return Authorization Response
Return Result
The return authorization request is passed from the point-of-return to Returns Management when evaluation is invoked. The return authorization response is returned by Returns Management to show the result of evaluation. The return result is passed by the point-of-return to Returns Management to initiate scoring.
This section describes the integration of Returns Management with an external point-of-return, using an example transaction and sample XML messages that are sent between the point-of-return and Returns Management.
To more clearly illustrate the XML messages, this chapter provides a scenario of a customer returning items under different situations. Each situation has a sample of the XML message with details around each element in the XML. There is a sample XML file for each of the three basic messages:
Return Authorization Request
Return Authorization Response
Return Result
Each of these messages has a corresponding XSD that defines the valid XML for each message.
John Smith wants to return some sporting equipment he has purchased. This example examines the message sent from the point-of-return to Returns Management when he first wants to return the items. Returns Management responds by asking for the positive ID. A second return request is made from the point-of-return to Returns Management with the additional ID information. Returns Management then responds with its decision.
The customer decides he wants to return the items. Then, for whatever reason, the return is voided. Finally, the customer decides to re-return the items when Returns Management is offline.
All XSDs referenced are provided in the Returns Management installation material. Table 9-2 identifies XSD file locations within the install package.
Table 9-2 XSD Locations
Document Name | Location |
---|---|
Return Authorization Request |
Retail-public-payload-java-beans.jar/META-INF/xsd/retail/integration/base/bo/RetAuthDesc/v1/RetAuthDesc.xsd |
Return Authorization Response |
Retail-public-payload-java-beans.jar/META-INF/xsd/retail/integration/base/bo/RetAuthResDesc/v1/RetAuthResDesc.xsd |
Return Result |
Retail-public-payload-java-beans.jar/META-INF/xsd/retail/integration/base/bo/RetResultDesc/v1/RetResultDesc.xsd |
In this scenario, John Smith has decided he wants to return some baseballs. He goes to the point-of-return which emits the following message:
Example 9-1 Initial Return Authorization Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <RetAuthDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1" xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ReturnRequest> <ItemReturnInfo> <ItemTransactionInfo> <receipted>false</receipted> <TransactionId> <ns2:TransIdDesc> <ns2:store_id> 12345 <ns2:store_id> <ns2:workstation_id> 124 <ns2:workstation_id> <ns2:sequence_number> 2 <ns2:sequence_number> <ns2:business_date>2005-12-31</ns2:business_date> </ns2:TransIdDesc> </TransactionId> <found>true</found> <valid_at_point_of_return>true</valid_at_point_of_return> <gift_receipt>false</gift_receipt> <purchase_date>2005-12-3100</ purchase_date> <delivery_date>2006-01-01</delivery_date> <validation_amount>40.00</validation_amount> <OriginalTender> <ns3:RetTendTypeDesc> <ns3:type>CASH</ns3:type> <ns3:amount>12.00</ns3:amount> </ns3:RetTendTypeDesc> <ns3:RetTendTypeDesc> <ns3:type>CRDT</ns3:type> <ns3:amount>38.00</ns3:amount> <ns3:card_number>2642</ns3:card_number> </ns3:RetTendTypeDesc> <OriginalTender> <sale_quantity>10</sale_quantity> </ItemTransactionInfo> <ns5:RetItemIdentDesc> <ns5:item_id>40020002</ns5:item_id> <ns5:item_type>Stock</ns5:item_type> <ns5:item_description>MLB Baseball</ns5:item_description> </ns5:RetItemIdentDesc> <return_reason> Customer Satisfaction </return_reason> <quantity>10.00</quantity> <amount_paid_per_unit>4.00</amount_paid_per_unit> <item_condition>Damaged</item_condition> <requested_adjusted_price>4.00</requested_adjusted_price> <manually_entered>false</manually_entered> </ItemReturnInfo> <return_store_id>04241</return_store_id> <return_workstation_id>123</return_workstation_id> <return_business_date>2013-03-04T00:00:00-06:00</return_business_date> <return_date>2013-03-14T05:49:30.700-06:00</return_date> <employee_id>20051</employee_id> <currency_iso_code>USD</currency_iso_code> <ns6:RetStoreLangDesc> <ns6:store_locale>en</ns6:store_locale> <ns6:operator_locale>en</ns6:operator_locale> <ns6:receipt_locale>en</ns6:receipt_locale> </ns6:RetStoreLangDesc> <RetCustomerInfo> <customer_id>80012</customer_id> <RetCustomerInfo> <transaction_type>Return</transaction_type> </ReturnRequest> </RetAuthDesc>
The entire request has a root element of <RetAuthDesc>.
The following sub- elements, unless specified otherwise, are of type String and are required.
Each return request is based around returning a discrete number of items. Each unique type of item has a corresponding itemReturnInfo element. This means that if a customer is returning ten baseballs and two bats, then there are two itemReturnInfo elements, not twelve.
This complex type describes the transaction during which the item was originally purchased.
This Boolean element tells Returns Management whether the customer has a receipt for this item. Non-receipted returns are allowed, but can trigger a different return policy.
This complex type identifies the ARTS-compliant transaction of the original purchase, if any.
These elements correspond to the parts of the ARTS-compliant transaction ID.
Note:
|
This Boolean element tells Returns Management if the transaction ID from the <transactionID> element was found. This element exists because it is possible to have a transaction number, for example, from a receipt, that is not found by the point-of-return when it queries existing transaction data. This element is required, but is only relevant if there is a transaction ID. If there is no <transactionID> element, this value should be set to false.
This Boolean element tells Returns Management if the transaction ID from the <transactionID> element is considered valid by the point-of-return. Any transaction ID that is found should set this value to true. If the ID is not found, the point-of-return should decide if the transaction ID appears to be legitimate and set this value accordingly.
This Boolean element tells Returns Management if the receipt presented at the point-of-return is a gift receipt. This element should not be included in the message if the <receipted> element is false.
These date elements refer to the purchase and delivery dates of the item being returned, respectively. If this data cannot be determined at the point-of-return, these elements should be omitted.
This optional element represents the dollar amount of the items being returned. This is only included when there is no found transaction but there is a valid transaction ID. This could happen if, for example, a customer has a receipt with a transaction number and amount on it, but the point-of-return cannot find the transaction in storage.
This complex type represents the original tenders used to purchase these items. Though this type is required, the list of original tenders can be empty, for example, for a non-receipted, non-transaction ID return.
For each original tender that the point-of-return knows about, there is a tender type entry.
Note: There might be no tender type entries (for example, for non-receipted returns), one entry, or many entries (for a split-tender scenario, such as an item that was bought partially with a gift card and partially with cash). |
These three elements describe the tender used. The <type> element is the only required element and is expected to match the standard four letter Oracle Retail tender types, for example, CASH. The <amount> element is an optional decimal value. The <cardNumber> element is listed as optional, but should be filled in with the appropriate card number if the tender type is CRDT.
This element represents the original quantity of items sold to the customer. A customer might want to return only one out of ten items they have bought. This original sale quantity is compared to previous returns Returns Management knows about. If the sum of items from previous returns plus the items from this return is greater than the sale quantity, Returns Management can flag and deny this return attempt.
This complex type identifies which item is being returned.
Returns Management relies on the <itemID> when referring to an item that it can look up in the AS_ITM table of the Oracle Retail data model. Though the XSD enables <itemDescription> to be included, it is unused by the code.
The <itemType> element describes the type of the item as evaluated by ItemTypeEvaluator. The user interface uses the ItemTypes parameter. The point-of-return and Returns Management must agree on valid values for this element.
The reason for which the item is being returned. This required element is used by the class ReturnReasonEvaluator. Based on the text provided here, the evaluator can choose various responses during policy initiation. The user interface uses the ReturnReasons parameter. The point-of-return and Returns Management must agree on valid values for this element.
This is the quantity being returned. Non-unitary units of measure, for example, feet, should be expressed in a decimal format, such as 1.5 feet for 18 inches.
The amount paid per item on this return.
This element is currently unused by Returns Management.
This element is set to the price at which the point-of-return wants to return the item. For instance, the point-of-return might request to return the item for less than the original sales price. This value is compared to the original price in PriceAdjustmentAmountEvaluator class. That rule initiates different actions depending on the ratio of the adjusted price to the original price per unit.
This element reflects the condition of the item. This value is used by the ItemConditionEvaluator class. Like the <returnReason> element, the legal values for this element need to be agreed upon by the point-of-return and Returns Management. The user interface uses the ItemConditions parameter. The point-of-return and Returns Management must agree on valid values for this element.
This required Boolean element denotes if the information in the <transactionID> element was manually entered at the point-of-return. This element should be false if there is no transaction ID.
These are the IDs of the store, workstation, and employee that are initiating the return, respectively. The employee ID is used for tracking cashier exceptions and is expected to correspond to an entry into the Oracle Retail employee table.
This element type is optional for loyalty. This value is used by the CustomerTypeEvaluator class.
These complex element types represent information about the customer returning the items.
Note: Only one of these info types can be present in the return request. |
The <customer_id> element corresponds to the Oracle Retail customer ID.
Note: This element is different from the Returns Customer ID in the Returns Management customer table, which is keyed off of positive ID. |
The <transaction_type> element corresponds to the type of return requested by the point-of-return. Valid values are defined by the parameter RefundTypes. The point-of-return and Returns Management must agree on valid values for this element. This parameter is defined in returnsmgmt.xml
. Default values are:
Return
Layaway_Cancellation
Order_Cancellation
Price_Adjustment
After the initial return request has been submitted, Returns Management determines that it needs a positive ID from the customer. Returns Management responds, indicating that the point-of-return should obtain the ID from Mr. Smith.
Note: The following positive ID types are supported in the base integration between the point-of-return and Returns Management:
Any other positive ID types set up in the point-of-return are not supported in the base integration between the point-of-return and Returns Management. |
Example 9-2 Return Authorization Response Requesting Positive ID
<ns7:RetAuthResDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1" xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ns7:ReturnResponse> <ns7:return_ticket_id>04241-123-1025-2006-005021791</ns7:return_ticket_id> <ns7:response_approve_deny_code>Denial</ns7:response_approve_deny_code> <ns7:ItemReturnResponse> <ns5:RetItemIdentDesc> <ns5:item_id>40020002 <ns5:item_id> </ns5:RetItemIdentDesc> <ns7:response_code>10</ns7:response_code> <ns7:approve_deny_code>Denial</ns7:approve_deny_code> <ns7:ResponseDescription> <ns7:ShortResponseDesc> <ns6:RetStoreLangDesc> <ns6:store_locale>Denied</ns6:store_locale> <ns6:operator_locale>Denied</ns6:operator_locale> <ns6:receipt_locale>Denied</ns6:receipt_locale> </ns6:RetStoreLangDesc> </ns7:ShortResponseDesc> <ns7:LongResponseDesc> <ns6:RetStoreLangDesc> <ns6:store_locale>Insufficient Quantity</ns6:store_locale> <ns6:operator_locale>Insufficient Quantity</ns6:operator_locale> <ns6:receipt_locale>Insufficient Quantity</ns6:receipt_locale> </ns6:RetStoreLangDesc> </ns7:LongResponseDesc> </ns7:ResponseDescription> <ns7:RefundTenders> </ns7:RefundTenders> </ns7:ItemReturnResponse> </ns7:ReturnResponse> </ns7:RetAuthResDesc>
The entire request has a root element of <RetAuthResDesc>.
The following sub- elements, unless specified otherwise, are of type String and are required.
This element refers to the return ticket created by Returns Management. The point-of-return needs to use this element in future communications with Returns Management about this return (for example, in response to a request for positive ID or when sending a final result).
If there are multiple item responses, then the most cautious <approve_deny_code> value is used.
There are exceptions to the behavior of this element. If a current entry is found in the customer service override table (RM_CT_SV_ORD) that matches this Returns Management customer and is active for the same date as the return, and the response would be a denial, then this value is set to Approved and the optional <availableCustomerServiceOverride> element is set.
This element informs the client in which language the <ShortResponseDesc>, <LongResponseDesc>, <ReceiptMessageDesc>, and other elements are sent. Currently, this is always en_US for English.
This element contains the detailed information about each of the items to which Returns Management is responding. There can be many of these elements in a transaction.
This complex type identifies which item is being returned.
Note: Returns Management sets the <item_id> sub-element only. |
Returns Management has a response associated with each item. These response codes are configured by the rule actions of the policy that Returns Management chose to execute. The codes are contained in the table RM_RSPS_RC.
The three values here correspond to the ID_RPSS_RC, TY_RSPS, and DE_RSPS respectively. The <response_code> element itself is an integer that corresponds to an ID of a response code. The <approve_deny_dode> is one of Denial, Mgr Overridable Denial, Contingent Authorization, or Authorization. The <ShortResponseDesc> is the short description of the response. Though these fields are required, in the message they can be ignored by the point-of-return since the <customer_info_required> element is true.
If this value is set to true, Returns Management is asking the point-of-return to prompt for Encrypted Positive ID. If this value is not present the point-of-return should assume that it is false.
Once the point-of-return has gotten a positive ID for Mr. Smith, it returns that information to Returns Management along with the data from the original return request.
Note: The <itemreturnInfo> content is the same as in and has been left out for brevity. |
Example 9-3 Second Return Authorization Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> RetAuthDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1" xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ReturnRequest> <ItemReturnInfo> ... </ItemReturnInfo> <return_store_id>04241</return_store_id> <return_workstation_id>123</return_workstation_id> <employee_id>20051</employee_id> <MoreCustomerInfo> <last_name>Smith</last_name> <first_name>Carlos</first_name> <middle_name>Juan</middle_name> <gender>Male</gender> <birth_date>1972-06-25</birth_date> <address1>1234 Example Blvd</address1> <address2/> <city>Miami</city> <state>FL</state> <postal_code>33056</postal_code> <country>US</country> <telephone_local_number>5551212</telephone_local_number> </MoreCustomerInfo> <PositiveId> <id>12345678</id> <type>DriversLicense</type> <issuer_country>US</issuer_country> <issuer_state>US</issuer_state> <issued>2004-01-01</issued> <expiration>2007-01-01</expiration> </PositiveId> <transaction_type>Return</transaction_type> <returnTicketID>04241-123-1025-2006-005021791</returnTicketID> </ReturnRequest> </RetAuthDesc>
The entire request has a root element of <RetAuthDesc>.
Returns Management works with two different customer data stores. The first data store is the Returns Management customer data store, which is keyed off of positive IDs. This is the set of customers used for exception tracking. The second data store is the standard Oracle Retail customer data store. Returns Management attempts to link customers for which it has a positive ID to customers in the Oracle Retail customer data store, creating customers if necessary.
For purposes of the Returns Management customer, only the <PositiveId> element is relevant. Returns Management either looks up or creates the customer corresponding to the positive ID. For the Oracle Retail customer, there are two elements which matter: <customer_id> (underneath <CustomerInfo>) and <MoreCustomerInfo>. If the <customer_id> is passed in, Returns Management assumes that this is the Oracle Retail customer relevant to the message. If the <customer_id> element is absent, and both the <PositiveId> and the <MoreCustomerInfo> elements are present, then Returns Management not only looks up or creates the Returns Management customer, but it also creates a new Oracle Retail customer and associates it with the Returns Management customer.
These examples are contrived to display the <CustomerInfo> and <MoreCustomerInfo> elements. In the first message, the point-of-return had a valid customer ID. In this message, the XML is constructed to imply that Returns Management should create a new customer matching the positive ID. In a real usage scenario, if the point-of-return knew the Oracle Retail customer but just needed to collect positive ID, the point-of-return would send the <CustomerInfo> element again rather than the <MoreCustomerInfo> element.
This element contains the information necessary to create an Oracle Retail customer.
These elements contain the last and first names (respectively) of the new Oracle Retail customer.
These optional elements contain the middle name, the gender, and the birth date of the new Oracle Retail customer. Notice that these elements are all strings, including birth date. Also notice that the gender element is constrained to either male or female.
These elements correspond to the usual two address lines of a customer. In this example, though <address2> is present, it is blank.
These elements are further parts of the customer address. In the US, the state and postal code would correspond to the state and zip code. In Canada, they would correspond to the province and postal code.
This element corresponds to the country in which the customer resides.
These two optional elements reflect the telephone number and area code. For a number such as 888-555-1212, the 888 would be in the <telephone_area_code> element while the 5551212 would be in the <telephone_local_number> element.
Positive ID refers to a customer presenting credentials (such as a driver's license) to authenticate their identity. The positive ID is used to reference the Returns Management customer. This element encodes information about the type of positive ID gathered by the point-of-return. See above for a discussion of the Returns Management customer versus the Oracle Retail customer.
The unique identifier on the positive ID which should be an encrypted value.
The type of identification presented. Valid types are DriversLicense, MilitaryID, Passport, and StateCard.
This is the issuing authority of the identification. For StateCard, this is the state which issued the card. For Passport, this is the country which issued the passport.
These two optional date elements reflect the date of issue and the date of expiration, respectively, of the positive ID.
This element is the same as the element in the initial return request.
By setting the <return_ticket_id> element, the point-of-return lets Returns Management know that it is responding to a request for more information. The element should be set to the ticket ID sent from Returns Management in the previous return response. In this case, the element has been set to 04241-123-1025-2006-005021791 to match our previous message.
Now that Returns Management has obtained a positive ID, it can tell the point-of-return about its decision of whether to allow the return of the items.
In this scenario, Mr. Smith has been returning a lot of items lately and has had an entry put into the exception file. This would normally result in a denial. However, Mr. Smith's agent has called the customer service center and asked them to accept the return. They have entered an entry into the customer service override table for Mr. Smith. Returns Management checks for these entries while it creates the final response. In this case, since it has found one, Returns Management authorizes the return but marks it as using a customer override.
Example 9-4 Second Return Authorization Response
<ns7:RetAuthResDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1" xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ns7:ReturnResponse> <ns7:return_ticket_id>04241-123-1025-2006-016085229</ns7:return_ticket_id> <ns7:response_approve_deny_code>Authorization </ns7:response_approve_deny_code> <ns7:avail_cust_service_override >true</ns7:avail_cust_service_override > <ns7:receipt_message_number >1</ns7:receipt_message_number> <ns7:ReceiptMessageDesc> <ns6:RetStoreLangDesc> <ns6:store_locale> Thank You for Shopping </ns6:store_locale> <ns6:operator_locale> Thank You for Shopping </ns6:operator_locale> <ns6:receipt_locale> Thank You for Shopping </ns6:receipt_locale> </ns6:RetStoreLangDesc> </ns7:ReceiptMessageDesc> <ns7:ItemReturnResponse> <ns5:RetItemIdentDesc> <ns5:item_id>11111</ns5:item_id> </ns5:RetItemIdentDesc> <ns7:response_code>150</response_code> <ns7:approve_deny_code>Mgr Overridable Denial</ns7:approve_deny_code> <ns7:ResponseDescription> <ns7:ShortResponseDesc> <ns6:RetStoreLangDesc> <ns6:store_locale> Mgr Overridable Denial </ns6:store_locale> <ns6:operator_locale> Mgr Overridable Denial </ns6:operator_locale> <ns6:receipt_locale> Mgr Overridable Denial </ns6:receipt_locale> </ns6:RetStoreLangDesc> </ns7:ShortResponseDesc> <ns7:LongResponseDesc> <ns6:RetStoreLangDesc> <ns6:store_locale>Insufficient Quantity</ns6:store_locale> <ns6:operator_locale>Insufficient Quantity</ns6:operator_locale> <ns6:receipt_locale>Insufficient Quantity</ns6:receipt_locale> </ns6:RetStoreLangDesc> </ns7:LongResponseDesc> </ns7:ResponseDescription> <receipt_message_number>1</receiptMessageNumber> <receiptMessageDescription> <ns6:RetStoreLangDesc> <ns6:store_locale> Thank You for Shopping </ns6:store_locale> <ns6:operator_locale> Thank You for Shopping </ns6:operator_locale> <ns6:receipt_locale> Thank You for Shopping </ns6:receipt_locale> </ns6:RetStoreLangDesc> </receiptMessageDescription> <refundTenders/> </itemReturnResponse> </ReturnResponse> </RetAuthResDesc>
Note: The return ticket ID in this response is different from the one sent in the first response. Each new return request generates a new return ticket ID. |
This optional Boolean element is only set when:
The overall approve or denial code is a denial.
This Returns Management customer has an active entry in the customer service override table.
When this item is present, it is always true. For details about the approve and deny code process, see "<response_approve_deny_code>".
Returns Management has a number of receipt messages that it can send back to the point-of-return. These messages are intended to be printed on the receipt, but obviously the point-of-return can do what it would like with them. Each message has both a number and a description. The number is provided for internationalization purposes and the message is provided to make the XML more human readable.
Note that there is both a receipt message associated with both the overall return response as well as with each item on the response. The overall message is determined in the same manner as the overall response code. That is, the most cautious individual response code determines both the overall response as well as the overall receipt message.
This is the text associated with the receipt message number. This text is in the language of the <RetStoreLangDesc> element.
This is the same element as detailed in the initial return response.
This is the same element as returned in the first return response. In this case, the sub-elements of this complex type contain detailed information about the decision of Returns Management regarding the returnability of this item.
This element is currently unused.
This is the receipt message number associated with the individual item. See "<receipt_message_number>, positive integer".
This element corresponds to the disposition of the item after it has been returned, for example, ”keep frozen”. It corresponds to the table in ID_DPSN_CD in the ARTS schema. However, this element is currently not set.
This is the receipt message text associated with the individual item. See "<ReceiptMessageDesc>".
This element is currently unused.
Once the positive ID has been collected and Returns Management has told the point-of-return about the returnability of the item, the point-of-return processes the return as necessary. Once the return has been completed, the point-of-return sends Returns Management a return result message.
Example 9-5 Return Result
<ns8:RetResultDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1' xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ReturnResult> <return_ticket_id>04241-123-1025-2006-016085229</return_ticket_id> <ReturnTransactionID > <TransIdDesc> <store_id>04241</store_id> <workstation_id>123</workstation_id> <sequence_number>250</sequence_number> <business_date>2006-10-25</business_date> </TransIdDesc> </ReturnTransactionID> <ItemReturnResult> <RetItemIdentDesc> <item_id>40020002</item_id> </RetItemIdentDesc> <quantity_returned>10</quantity_returned> <final_result_code>Authorized</final_result_code> <OverrideInfo> <manager_id>20008</manager_id> <override_obtained>true</override_obtained> <tender_override>false</tender_override> </OverrideInfo> <OriginalTransactionID> <TransIdDesc> <storeID>12345</storeID> <workstationID>124</workstationID> <sequenceNumber>2</sequenceNumber> <businessDate>2005-12-31</businessDate> <TransIdDesc> </OriginalTransactionID> <ReturnTender> <<RetTendTypeDesc> <type>CASH</type> <amount>40.00</amount> </RetTendTypeDesc> </ReturnTender> </ItemReturnResult> </ReturnResult> </RetResultDesc>
Once again, note the return ticket ID. It is the ticket ID referring to the second return response.
This element refers to the ARTS-compliant return transaction generated by the point-of-return. It has the same format as the <TransactionID> element of the return request.
This complex element represents detailed information about each item returned.
This number reflects the quantity actually returned by the point-of-return.
This element has one of two values, Authorized or Denial. For items that are returned, the value is set to Authorized.
This complex type is included in the result if the point-of-return decided to override a return decision rendered either by Returns Management or locally.
The ID (from the ARTS-compliant table PA_EM) that corresponds to the employee ID of the manager who overrode the return decision.
This element is set to true if the override was about the returnability of the item.
This element is set to true if the override was about which tenders to return money on.
This element refers to the ARTS-compliant transaction associated with the original sale. This element has the same format as the <transactionID> element of the return request. This element is currently unused by Returns Management.
This element is a list of tenders. It describes the number of tenders, and the amount of each one, used by the point-of-return to return money to the client. It has the same format as the <OriginalTender> element of the return request.
Mr. Smith has proven to be indecisive and decides that he wants to have his baseballs after all. He wants to void the return and receive the items back. To accommodate this, the point-of-return voids the previous return and informs Returns Management of the fact.
Example 9-6 Void Return Result
<ReturnResult> <return_ticket_id>04241-123-1025-2006-016085229</return_ticket_id> <ReturnTransactionID> <TransIdDesc> <store_id>04241</store_id> <workstation_id>123</workstation_id> <sequence_number>250</sequence_number> <business_date>2006-10-25</business_date> </TransIdDesc> </ReturnTransactionID> <return_voided>true</return_voided> </ReturnResult>
In this message, you see the same return ticket ID and the same return transaction ID of the preceding return result. This is used to let Returns Management know which return is being voided. The only new element is the <return_voided> element.
This element shows that the return referenced by the <return_ticket_id> element has been voided. Though this element is optional, exactly one of either <return_voided> or <ItemReturnResult> must appear in the return result. Thus, when this element is present, it must always be true.
Finally, Mr. Smith decides that he does, in fact, want to return the baseballs. When he returns to do so, the point-of-return is offline from Returns Management. The point-of-return makes it own decisions about the returnability of the items. For the sake of illustration, the point-of-return makes exactly the same decisions that Returns Management did previously, though there is no requirement for this.
Note: The <iItemReturnInfo> content is the same as in Example 5-1 and has been left out for brevity. |
Example 9-7 Offline Return Result
<ns8:RetResultDesc xmlns:ns2="http://www.oracle.com/retail/integration/base/bo/TransIdDesc/v1" xmlns="http://www.oracle.com/retail/integration/base/bo/RetAuthDesc/v1" xmlns:ns4="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1" xmlns:ns3="http://www.oracle.com/retail/integration/base/bo/RetTendTypeDesc/v1" xmlns:ns5="http://www.oracle.com/retail/integration/base/bo/RetItemIdentDesc/v1" xmlns:ns6="http://www.oracle.com/retail/integration/base/bo/RetStoreLangDesc/v1" xmlns:ns7="http://www.oracle.com/retail/integration/base/bo/RetAuthResDesc/v1" xmlns:ns8="http://www.oracle.com/retail/integration/base/bo/RetResultDesc/v1"> <ReturnResult> <offline_date>2006-05-16</offline_date> <OfflineRequest> <RetAuthDesc> <ReturnRequest> <ItemReturnInfo> ... </ItemReturnInfo> <return_store_id>04241</return_store_id> <return_workstation_id>123</return_workstation_id> <employee_id>20051</employee_id> <CustomerInfo> <customer_id>8885551212</customer_id> </CustomerInfo> <PositiveID> <id>12345678</id> <type>DriversLicense</type> <issuer_country>US</issuer_country> <issuer_state>TX</issuer_state> <issued>2004-01-01</issued> <expiration>2007-01-01</expiration> </PositiveID> <transaction_type>Return</transaction_type> </ReturnRequest> </RetAuthDesc> </OfflineRequest> <ReturnTransactionID> <TransIdDesc> <store_id>04241</store_id> <workstation_id>123</workstation_id> <sequence_number>263</sequence_number> <business_date>2006-10-25</business_date> </TransIdDesc> </ReturnTransactionID> <ItemReturnResult> <<RetItemIdentDesc>> <item_id>40020002</item_id> </<RetItemIdentDesc>> <quantity_returned>10</quantity_returned> <final_result_code>Authorized</final_result_code> <OverrideInfo> <manager_id>20008</manager_id> <override_obtained>true</override_obtained> <tender_override>false</tender_override> </overrideInfo> <OriginalTransactionID> <TransIdDesc> <store_id>12345</store_id> <workstation_id>124</workstation_id> <sequence_number>2</sequence_number> <business_date>2005-12-31</business_date> <TransIdDesc> </OriginalTransactionID> <ReturnTender> <RetTendTypeDesc> <type>CASH</type> <amount>40.00</amount> </RetTendTypeDesc> </ReturnTender> </ItemReturnResult> </ReturnResult> </RetResultDesc>
The offline result is effectively a return result with two additional elements. The first element is the date of the offline return. The second element is a return request message encapsulated in the <offlineRequest> element.
This element is the original date of the offline return. Though this element is optional in the XSD, it is required when processing an offline return.
The <OfflineRequest> element is an embedded return request. It has the exact same format as a normal return request message except that the root <ReturnRequest> element is replaced by the <OfflineRequest> element.
Note: The XSD specifies that the result message has either an <OfflineRequest> element or a <return_ticket_id> element, but not both. |
This element refers to the ARTS-compliant return transaction generated by the point-of-return. It has the same format as the <TransactionID> element of the return request.
This element contains the detailed data about the items returned in this offline request. It has the same format as the original return result previously described.
The following are types of implementation decisions.
Synchronous communication involves a client sending a message to a server and then pausing while it waits for a response. Asynchronous communication enables a client to send a message to the server and then immediately resume operations. Synchronous communication is usually more straightforward than asynchronous communication, but increases binding between a client and a server and can degrade concurrency. Asynchronous communication has the opposite problems: it is usually more complicated, but encourages decoupling and throughput.
Additionally, synchronous communication is necessary when a client needs a time-sensitive response to a message.
Returns Management prefers to use asynchronous communication. This is mainly due to concurrency. When communication is asynchronous, it can be off-loaded onto a lightly loaded machine or scheduled to run at a time when there is relatively little system activity. Also, the communication can be more easily chained, for example, by inserting an arbitrary number of message forwarders between the client and server, or by inserting a message broadcaster. This enables greater flexibility in future system growth. However, asynchronous messaging is poorly suited for real time responses to messages.
Because asynchronous messaging provides greater latitude at installation and higher concurrency, the result message is implemented as an asynchronous call. Evaluation, however, has a strong requirement for a rapid response, for example, a customer is physically waiting at the point-of-return for a return approval. This evaluation is implemented as a synchronous call.
Extensible markup language (XML) is a text format that is language independent and human legible. It has wide support in a variety of programming languages and a robust description language, XML Schema Definition (XSD). Being a text format, XML is capable only of encoding data.
JavaBeans are Java language constructs that mainly encapsulate data in an object class. Being objects, however, JavaBeans can optionally contain behavior as well as data. Also because they are objects, both the originator and the receiver of a JavaBean must have access to compatible versions of the class file.
JavaBeans are a well known Java idiom and have a great deal of support in the Java Development Kit (JDK). However, they are a Java-specific solution. Furthermore, XML is more accessible to a non-technical audience than either Java source or Java runtime debugging environments. Also, XML is the standard of web service communication. Therefore, the messages that Returns Management passes are XML based rather than JavaBean (or Java Object) based. The XML is eventually transformed into JavaBeans. This transformation to and from JavaBeans is facilitated by Java XML Binding (JAXB) code.
Web services are language neutral, similar to XML. Web services also provide a well-defined publishing and discovery mechanism: Universal Description, Discovery and Integration (UDDI).
Note: All POS Suite web services are deployed on an JAX-WS framework. JAX-WS handlers security module is used for authentication. |
The previous sections have discussed details of the XML messages. This section provides more information about important elements.
In Table 9-3, the mark (x) indicates that the element is required and needs to have an appropriate value for that scenario. A value true or false indicates that this element should be set to this explicit value.
The Element column represents the various elements; the other columns represent the different scenarios. The XPath expressions clarify where the elements are in relationship to the entire message.
Note: In subsequent Positive ID messages, all original scenario elements should be sent. |
Table 9-3 Required Elements By Return Request
Receipted | |||||
---|---|---|---|---|---|
Element | Non-receipted | No transaction data | Has data, no transaction found | Has data, transaction found | Positive ID |
/ReturnRequest/ItemReturnInfo/ItemTransactionInfo |
|||||
receipted |
false |
true |
true |
true |
NA |
TransactionID |
NA |
NA |
X |
X |
NA |
found |
false |
false |
false |
true |
NA |
valid_at_point_of_return |
false |
false |
X |
true |
NA |
validation_amount |
NA |
NA |
X |
NA |
NA |
OriginalTender |
X |
X |
X |
X |
NA |
/ReturnRequest/ItemReturninfo |
|||||
RetItemIdentDesc |
X |
X |
X |
X |
NA |
return_reason |
X |
X |
X |
X |
NA |
quantity |
X |
X |
X |
X |
NA |
manually_entered |
false |
false |
X |
false |
NA |
/ReturnRequest |
|||||
return_store_id |
X |
X |
X |
X |
NA |
return_workStation_id |
X |
X |
X |
X |
NA |
employee_id |
X |
X |
X |
X |
NA |
CustomerInfo or MoreCustomerInfo |
X |
X |
X |
X |
NA |
id |
NA |
NA |
NA |
NA |
X |
transaction_type |
X |
X |
X |
X |
NA |
return_Ticket_id |
NA |
NA |
NA |
NA |
X |
In Table 9-4, the Element column refers to the elements in the return response. The remaining columns describe the various use cases. A mark (x) means that the point-of-return should be concerned with this data point when encountering it. A true or false value means that the point-of-return examines this data point for this value to determine the use case. The XPath expressions help the reader orient themselves with the elements.
This is the minimum amount of data a point-of-return needs to implement. Additionally, the point-of-return must decide how to interpret the approval or denial of the <response_approve_deny_code> element.
Keep in mind that some items might be approved while others are denied.
Table 9-4 Required Elements By Return Response
Element | Approval or Denial | Positive ID Required | CS Override |
---|---|---|---|
/ReturnResponse |
|||
return_ticket_id |
X |
X |
X |
response_approve_deny_code |
X |
NA |
X |
available_customer_service_override |
NA |
NA |
true |
/ReturnResponse/ItemReturnResponse |
|||
RetItemIdentDesc |
X |
X |
X |
approve_deny_code |
X |
NA |
NA |
RefundTenders |
X |
NA |
X |
customer_info_required |
NA |
true |
NA |
In Table 9-5, the Element column is the list of elements the point-of-return needs to send in the ReturnResult message. A mark (x) indicates that this element should be present when sending this type of response to Returns Management. A true or false value indicates that this element should be set explicitly to this value when sending this type of message. The XPath expressions help orient the reader.
Table 9-5 Required Elements By Return Result Use Case
Element | Standard Result | Offline Return | Voided Return |
---|---|---|---|
/ReturnResult |
|||
returnticket_id |
X |
NA |
X |
offline_date |
NA |
X |
NA |
OfflineRequest |
NA |
X |
NA |
return_transaction_id |
X |
X |
X |
return_voided |
NA |
NA |
true |
/ReturnResult/ItemReturnResult |
|||
RetItemIdentDesc |
X |
X |
NA |
quantity_returned |
X |
X |
NA |
final_result_code |
X |
X |
NA |
OverrideInfo Note: This element should be included only if there was an override. |
X |
X |
NA |
ReturnTender |
X |
X |
NA |
The web service exposes two methods. Table 9-6 describes these methods, with their parameters.
Table 9-6 Web Service Methods
Method Name | Input | Output |
---|---|---|
evaluateReturnRequest |
String (RetAuthDesc) |
String (RetAuthResDesc) |
processFinalResult |
String (RetResultDesc) |
None |
Note that though the web services expect to produce and consume XML, the XML is passed and returned as a simple string rather than a DOM object.
By default, the web service is accessed at the following URL:
http://hostname:port/ReturnsMgmtBean/ReturnsMgmtService
To access WSDL file:
http://hostname:port/ReturnsMgmtBean/ReturnsMgmtService?WSDL
Where hostname:port is replaced with the host and port to which the web service .ear file is deployed.
The Association for Retail Technology Standards (ARTS) is an international membership organization dedicated to reducing the costs of technology through standards. ARTS has four standards:
The Standard Relational Data Model
UnifiedPOS
IXRetail
Standard RFPs
For more information about ARTS, go to:
http://www.nrf-arts.org/
One of the goals of Returns Management is to reduce its dependency on external systems. At the same time, customers need traceability of Returns Management data back to original transaction data.
To account for this, the return request and return result messages sent to Returns Management contain the ARTS-compliant transaction IDs for the relevant transactions. Therefore, when a return request is made, Returns Management is told of the transaction ID, if any, of the original sale. When a return result is sent, Returns Management is told of the transaction ID of the return transaction. This ID is stored with the return ticket.
When Returns Management and Point-of-Service are integrated, Point-of-Service can collect positive IDs during return transactions in order to provide the following functionality:
Form and send Return Request messages to Returns Management
Interpret and present Returns Management Return Response messages
Form and send Final Result messages to Returns Management right before the return transaction is completed
Point-of-Service supports all Returns Management Return Response types. It accepts and manages Returns Management recommended tenders.
Returns Management can deliver an accept/deny response for attempted refunds on line items of return transactions as well as non-receipted return attempts through standard XML messages. The retailer can configure enterprise-wide, down to store-specific and item-specific, receipted and non-receipted policies that are applied to line items in transactions occurring at a point-of-sale or point-of-return. The policy definition, as well as accept/deny logic, is contained within the enterprise and therefore is abstracted from the point-of-sale or return such that Returns Management can work with any point-of-sale or return application, including web or phone order systems. Returns Management can count instances of behavior for customers and cashiers based on negativity activity and deny returns based on frequent suspicious activity. There are inquiry screens that can be used to research an attempted refund or a particular score and its history.
Communication with Returns Management is available only when the Point-of-Service server is online. If the Point-of-Service server goes offline at any time during authorization or when sending the final result, the authorization request and final result information are saved in Point-of-Service as offline return information, the message in EJournal is logged, and the offline return information is sent to Returns Management when it is available.
The Oracle Retail Returns Management exception file is created and maintained by Returns Management for use in detecting and preventing fraud at the point-of-return. The exception file acts as a constantly evolving knowledge base that can help the Authorization Engine decide which customers, items, cashiers, or stores are at higher risk for return fraud.
The exception file holds an exception counter for a customer that is incremented based on suspicious return activity. If an activity is selected for inclusion in the exception counter, the system adds 1 to the exception count for each suspicious shopping activity. Likewise, activities can be configured for cashiers.
Exceptions and counting are based on real-time refund attempt activities occurring at the point-of-sale or return using the return result message that is sent by the point-of-sale or return to Returns Management at the conclusion of a transaction with an attempted refund. Return activities include activities that increment counters such as a return transaction by the customer without a receipt and with no retrieval of the original transaction, five same day returns as purchases within the last three days, and three returns today. In turn, activity thresholds might be breached and counting generated based on those thresholds.
The exception file holds an entry for each factor that triggers a count addition.
This section describes exception file count calculation for the following:
Customer positive ID consisting of ID type, number, and issuer
Exception count
Cashier ID
Exception count
Exception (the return activity that was breached)
Target of the return activity (the customer ID, cashier ID)
Date/Time of the exception
Table 9-7 Overall Assumptions/Requirements
Reference | Description | Priority Order |
---|---|---|
EFA_AS_CAPTURE1 |
Every return transaction that takes place captures:
If customer positive ID is captured then accumulated exceptions can be checked to determine returnability. |
0 |
EFA_AS_CAPTURE2 |
Every type of sale transaction captures the cashier performing the transaction, the store or channel where the purchase occurred, and the items being purchased. |
0 |
EFA_AS_KPI_DEF2 |
Key Performance Indicators might be based on calculations on a cashier or customer. |
0 |
EFA_AS_KPI_DEF3 |
A number of configurable KPIs are delivered in the product. |
0 |
EFA_AS_KPI_DEF4 |
Addition of a new KPI requires development work, since data calculation might be required. |
0 |
EFA_AS_CALC_REUSE |
Calculations are reused where possible. Parameters set for tracking exceptions and rules within policies are set independently and do not have to match each other. |
0 |
EFA_AS_RPRICE_DEF |
Item return price refers to the amount refunded to the customer upon return. If a restocking fee was applied, the item return price is the net of the original selling price minus the restocking fee. |
0 |
EFA_AS_FIRST_WRITE |
|
0 |
Note: Returns Management requires the use of a unique cashier ID for exception tracking. |
A return, for purposes of calculation, refers to an attempted return of a line item quantity.
Note: Returns count by type at the transaction level (unique line item level). This accommodates variations between points of sale that allow mixed situations or inherently disallow mixed situations. Counting at the quantity level could abnormally inflate exceptions, for example, returning a quantity of 8 china plates. Counting at the transaction level could exclude appropriate return or non-return counts due to the ability to mix returns from multiple original receipted transactions, or no receipt, within one Returns Management point-of-sale transaction. |
Counting unique exceptions at the transaction level is conducted so that the customer is not penalized twice for the same situation within one transaction. If an exception occurs multiple times in a single transaction, that is counted as a single exception. For example, if a customer returns three different items without a receipt in a single return transaction, only one exception is generated.
Table 9-8 offers exception counting examples.
Table 9-8 Exception Counting Examples
Scenario | Exceptions Counted |
---|---|
Return attempt for 5 different items:
|
1 count for without a receipt 1 count for with a receipt |
Return attempt for 4 different items, total quantity 5:
|
1 count for without a receipt 1 count for with a receipt |
Return attempt for 2 different items:
|
1 count for without a receipt 1 count for with a receipt |
Two renter line items and one non-renter line item on the same receipted return attempt:
The receipt is older than a parameterized number of days old (hence an expired receipt). |
1 renter return 1 expired receipted return |
Can mix returns both with and without receipts in the same transaction, as well as returns received from multiple transactions. In one return transaction, six line items could consist of:
|
1 count for without a receipt 1 count for with a receipt |
The following are types of returns exceptions.
Customer Exceptions can be flagged as behaviors that are tracked in the application, for use in Return Policies, using the Customer Exceptions to Track screen.
An exception is any activity that can be discerned from Return Ticket data, such as a non-receipted return, a return of an item contained in the Return Pattern Watch file, or a particular type of refund transaction such as a Price Adjustment.
When a customer exception occurs, a record is written to the exception file and the activity is available for research on that customer using the Customer Exception Search and Customer Exception Search Results screens.
The total number of exceptions that have occurred can be checked using a rule that can be included in return policies.
All of the exceptions are based on return ticket data.
Cashier Exceptions can be flagged as behaviors that are tracked in the application, for use in Return Policies, using the Cashier Exceptions to Track screen.
When a cashier exception occurs, a record is written to the exception file and the activity is available for research on that cashier using the Cashier Exception Search and Cashier Exception Search Results screens.
The total number of exceptions that have occurred can be checked using a rule that can be included in return policies.
All of the exceptions are based on return ticket data.
Cashier in this case is considered to be anyone captured as the employee on the return ticket, regardless of whether they have a cashier, associate manager, manager, or other store role.
The Returns Management customer import feature is a way for a retailer to import a large amount of pre-existing customer data into the data-store accessed by Returns Management. Besides the usual customer information, such as Name, Address and Phone, this feature also enables the retailer to assign an exception count to a customer, based on third-party information about an individual (for example, information from credit bureaus, information about criminal records and so on). In Returns Management, higher exception counts are indicative of customers whose past behavior is of concern from a returns standpoint.
Most of the customer information imported is the same as the customer information sent in the Returns Management Return Request XML message. The XML schema definition of this information was contained in the RM-CustomerImport.xsd
file:
The Customer Import XML is defined by the following schema file:
RM-CustomerImport.xsd
The xsd files can be found in the
archive.
<Install_DIR>/returnsmgmt/api/returnsSchemas.zip
The following is a listing of the RM-CustomerImport.xsd
file:
Example 9-8 RM-CustomerImport.xsd
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="ReturnsCustomers" type="ReturnsCustomersType"/> <xsd:complexType name="ReturnsCustomersType"> <xsd:sequence> <xsd:element name="ReturnsCustomer" type="ReturnsCustomerType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="ReturnsCustomerType"> <xsd:sequence> <xsd:element name="positiveID" type="PositiveIDInfo" /> <xsd:element name="customerInfo" type="MoreCustInformation" /> <xsd:element name="exceptionCount" type="xsd:integer" /> <xsd:element name="customerType" type="xsd:string" minOccurs="0" maxOccurs="1" /> <xsd:element name="notes" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="PositiveIDInfo"> <xsd:sequence> <xsd:element name="number" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="type" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="issuerCountry" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="issuerState" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="issued" type="xsd:date" minOccurs="0" maxOccurs="1" /> <xsd:element name="expiration" type="xsd:date" minOccurs="0" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="MoreCustInformation"> <xsd:sequence> <xsd:element name="lastName" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="firstName" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="middleName" type="xsd:string" minOccurs="0" maxOccurs="1" /> <xsd:element name="gender" minOccurs="0" maxOccurs="1"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="Male" /> <xsd:enumeration value="Female" /> </xsd:restriction> </xsd:simpleType> </xsd:element><!-- format of yyyyMMdd --> <xsd:element name="birthDate" type="xsd:string" minOccurs="0" maxOccurs="1" /> <xsd:element name="address1" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="address2" type="xsd:string" minOccurs="0" maxOccurs="1" /> <xsd:element name="city" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="state" type="xsd:string" minOccurs="1" maxOccurs="1" /><!-- zip code--> <xsd:element name="postalCode" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="country" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="telephoneLocalNumber" type="xsd:string" minOccurs="0" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> </xsd:schema>
The following is an example of the Returns Management Customer Import XML file.
Example 9-9 RMCustomerImport.xml
<?xml version="1.0" encoding="UTF-8"?> <ReturnsCustomers> <ReturnsCustomer> <positiveID> <number>MDAxMGbGwbmQ1Xj6usAD03MY8pQ=</number> <type>DriversLicense</type> <issuerCountry>US</issuerCountry> <issuerState>TX</issuerState> <issued>2005-01-01</issued> <expiration>2030-01-01</expiration> </positiveID> <customerInfo> <lastName>TX1000000</lastName> <firstName>Oracle1000000</firstName> <address1>Some address1</address1> <address2>Some address2</address2> <city>Austin</city> <state>TX</state> <postalCode>78759</postalCode> <country>US</country> <telephoneLocalNumber>5126715100</telephoneLocalNumber> </customerInfo> <exceptionCount>100</exceptionCount> <customerType>Gold</customerType> <notes>by ReturnsCustomerImport</notes> </ReturnsCustomer> </ReturnsCustomers>
The following parameter is used for the customer import feature:
ReturnsCustomerImportDuplicateRecordAction
Customer data imported through this feature is stored in one or more of the tables identified in Table 9-9.
Table 9-9 Customer Information Tables
Table name | Information held in table |
---|---|
RM_CT |
Returns Customer ID and Positive ID |
RM_CT_ID |
Returns Customer ID to Customer ID mapping |
RM_CT_SCR |
Customer exception count |
RM_CT_SV_OVRD |
Comments (notes) when exception count is changed |
PA_CT |
Customer ID |
PA_PRTY |
Customer ID to Party ID mapping |
PA_CNCT |
Customer last and first name |
LO_ADS |
Customer address |
PA_PHN |
Customer phone number |