Outbound Return API

Purpose: Order Management System allows you to send created return authorization information and completed return and exchange information to another system, such as a warehouse management system.

Outbound return information flow: This flowchart explains how return information is downloaded from Order Management System.

In this chapter:

• Generic Return Out Download Process

- Identifying Return Authorization Download Triggers

- When are Return Authorization Download Triggers Created?

- Return Download Processing

- Return Authorization Outbound Trigger Activities

- Return Authorization Outbound Trigger Rules

- Return Authorization Trigger Cleanup

• Order Management System Setup for the Outbound Return API

- System Control Values Related to the Return Out API

- Menu Options Related to the Return Out API

- Periodic Function Related to the Return Out API

• Return Authorization Outbound: Sample XML Messages

• Return Authorization Outbound XML Message (CWReturnRAOut)

Generic Return Out Download Process

The system creates return authorization download triggers in the Working with Outbound Interface Transactions (WOIT) menu option when a return authorization is created, changed, or deleted, based on the trigger rules defined for the Return Authorization Download (RETURN_OUT) integration layer job. The Return Authorization Outbound (RETURN_OUT) job in the Working with Integration Layer Processes (IJCT) menu option monitors the Working with Outbound Interface Transactions (WOIT) menu option for return authorization download triggers to process and generates a Return Authorization Outbound XML Message (CWReturnRAOut) to send to the remote system.

• Identifying Return Authorization Download Triggers

• When are Return Authorization Download Triggers Created?

• Return Download Processing

• Return Authorization Outbound Trigger Activities

• Return Authorization Outbound Trigger Rules

• Return Authorization Trigger Cleanup

Identifying Return Authorization Download Triggers

You can view all download triggers in the Working with Outbound Interface Transactions (WOIT) menu option.

Each trigger on the Work with Outbound Interface Transactions Screen contain a:

• File code: indicating the type of information to download and which job in the Working with Integration Layer Processes (IJCT) menu option processes the trigger. For return authorization download triggers, the File code is RAD, regardless of whether the activity was a created, changed, or deleted return authorization.

• Key: indicating the specific record to download. For return authorization download triggers, the Key identifies the specific company code, order number, ship to number, return authorization number, and return authorization line number associated with the return authorization download trigger. For example, the Key 00700001446001001001 indicates the return authorization download information is located in company 7 for order number 1446, ship to number 1, return authorization number 1, and return authorization line number 1.

• Capture type: indicating the type of activity performed against the record:

- A = the return authorization was created.

- C = the return authorization was changed.

- D = the return authorization was deleted.

When are Return Authorization Download Triggers Created?

The Create Return Download Triggers (K28) system control value controls whether the system creates return authorization download triggers in the Working with Outbound Interface Transactions (WOIT) menu option.

• If this system control value is selected, certain actions (see Return Authorization Outbound Trigger Activities) in Order Management System trigger the system to create return authorization download triggers in the Working with Outbound Interface Transactions (WOIT) menu option with a File code of RAD. The return authorization download (RAD) triggers that are in a Ready status in the Working with Outbound Interface Transactions (WOIT) menu option act as a "to do" list for the return authorization information that requires download.

• If this system control value is unselected, the system does not create return authorization download triggers in the Working with Outbound Interface Transactions (WOIT) menu option.

Return Download Processing

To generate a Return Authorization Outbound XML Message (CWReturnRAOut), the system:

1.

During certain activities (see Return Authorization Outbound Trigger Activities), evaluates the trigger rules defined for the Return Authorization Outbound (RETURN_OUT) job to determine if the return authorization download (RAD) trigger is created. The Return Authorization Outbound Trigger Rules for the Return Authorization Outbound (RETURN_OUT) job define the criteria the return authorization must meet in order for the system to create a return authorization download trigger.

2.

When active, the trigger monitor defined for the Return Authorization Outbound (RETURN_OUT) job looks for unprocessed return authorization download triggers to process at defined intervals, based on the Outbound delay time. The Return Authorization Outbound trigger monitor: • Looks for return authorization download triggers with the File code RAD and a status of ready (R). • Removes duplicate return authorization download triggers. See Return Authorization Trigger Cleanup. • Determines which return authorization to download, based on the return authorization download trigger Key. The Key field for return authorization download triggers consists of company code, order number, ship to number, return authorization number, and return authorization line number. For example, the Key 00700001446001001001 indicates the return authorization download information is located in company 7 for order number 1446, ship to number 1, return authorization number 1, and return authorization line number 1. • Sends the generated return authorization download message to the queues defined for the Return Authorization Outbound (RETURN_OUT) job that are active (the Enabled field is selected).

Return Authorization Outbound Trigger Activities

This table indicates:

• Which Order Management System activities create a return authorization download trigger.

• The type of activity performed against the return authorization:

- A = A return authorization was created.

- C = A return authorization was changed.

- D = A return authorization was deleted.

Note: Certain activities may create duplicate triggers; however, the Return Authorization Trigger Cleanup will remove any duplicates before generating a Return Authorization Outbound XML Message (CWReturnRAOut).

You can review the return authorization download triggers in the Working with Outbound Interface Transactions (WOIT) menu option.

The system creates a return authorization download trigger for the activities listed below only if the Create Return Download Triggers (K28) system control value is selected and the return authorization meets the criteria from the Return Authorization Outbound Trigger Rules.

Return Authorization Download (RAD) trigger created when:	Trigger Type
You create a return authorization (streamlined or non-streamlined) for an order line in the Work with Return Authorization (WRTA) menu option. The system creates a separate return authorization download (RAD) trigger for each return authorization detail line created. For exchanges, the system creates a return authorization download (RAD) trigger for the item being returned and not for the new exchange item. Note: The system does not create a return authorization download (RAD) trigger when you receive the return authorization or process the credit for the return authorization. See Introducing Return Authorizations (WRTA).	A
You create a mis-ship return in Order Maintenance or the Work with Return Authorization (WRTA; streamlined or non-streamlined) menu option. See Introducing Return Authorizations (WRTA).	A
You change a return authorization at the Change RA Detail Screen (non-streamlined returns) or Change RA Detail Screen (Complete/Process a Return for an Item) (streamlined returns) in the Work with Return Authorization (WRTA) menu option. For example, you change the quantity returned or the refund settings. Note: The system creates a return authorization download (RAD) trigger when you advance to either of these screens, even if you do not change any of the values on these screens. See Introducing Return Authorizations (WRTA).	C
You delete a return authorization (streamlined or non-streamlined) in the Work with Return Authorization (WRTA) menu option. The system creates a separate return authorization download (RAD) trigger for each return authorization detail line that is deleted. See Introducing Return Authorizations (WRTA).	D
You post a return in order entry. The system creates a separate return authorization download (RAD) trigger for each order line returned. For exchanges, the system creates a return authorization download (RAD) trigger for the item being returned and not for the new exchange item. See Posting a Return or Exchange Through Order Entry.	A
You post a return in order maintenance. The system creates a separate return authorization download (RAD) trigger for each order line returned. For exchanges, the system creates a return authorization download (RAD) trigger for the item being returned and not for the new exchange item. See Returning and Exchanging Items in Order Maintenance.	A
You post a return through the order API. The system creates a separate return authorization download (RAD) trigger for each order line returned. For exchanges, the system creates a return authorization download (RAD) trigger for the item being returned and not for the new exchange item. See Processing a Return in the Generic Order Interface (Order API).	A

Returns that do NOT generate a return authorization download (RAD) trigger: Regardless of the setting of the Create Return Download Triggers (K28) system control value, the system does not generate a return authorization download (RAD) trigger for returns received through the Inbound Return API; see Inbound Return API.

Return Authorization Outbound Trigger Rules

Return Authorization Outbound trigger rules define the criteria a return authorization must meet in order for the system to create a return authorization download trigger.

• If the return authorization meets the Return Authorization Outbound trigger rule criteria, the system creates a return authorization download trigger.

• If the return authorization does not meet the Return Authorization Outbound trigger rule criteria, the system does not create a return authorization download trigger.

You can define Return Authorization Outbound trigger rules for the Company and Order Type fields in the Order Header table. If you define more than one criterion, the return authorization must meet all of the criteria defined in order to generate a trigger.

Example: You define the following trigger rules for the Return Authorization Outbound job:

Return Authorization Outbound Trigger Rules
Order Header Criteria	Results
The Company field must equal 7 or 555.	The system creates a return authorization download trigger only if the return authorization being created or deleted in company 7 or 555.
The Order type must equal W.	The system creates a return authorization download trigger only if the return authorization being created or deleted is associated with an order whose order type is W.
The Company field must equal 7 or 555, AND the Order type must equal W.	The system creates a return authorization download trigger only if the return authorization being created or deleted is in company 7 or 555 and the return authorization is associated with an order whose order type is W.
no criteria defined	The system creates a return authorization download trigger for each return authorization created or deleted.

You can define trigger rules for the Return Authorization Outbound job at the Outbound Interface Trigger Rules Screen; see Defining Outbound Interface Trigger Rules.

Note: When you create trigger rules, the system does not validate that your entry is a valid value for the field or is within the maximum field positions. Refer to your Field (Table) Listing to review field attributes for the Order Header table.

Return Authorization Trigger Cleanup

Before processing the return authorization download triggers, the Return Authorization Outbound job looks for duplicate unprocessed return authorization download triggers.

Duplicate return authorization download triggers exist if more than one trigger has the same:

• File code RAD

• Capture type

• Key (company code + order number + ship to number + return authorization number + return authorization line number)

If duplicate return authorization download triggers exist, the system removes the duplicates, leaving only the most recent return authorization download trigger for that capture type.

Example: The following change return authorization download triggers exist in the Working with Outbound Interface Transactions (WOIT) menu option:

File	Type	Status	Key	Results
RAD	C	R	00700001446001001001	The system deletes 2 of these return authorization download triggers, leaving only one change trigger to process.
RAD	C	R	00700001446001001001
RAD	C	R	00700001446001001001

Note: If both an add (Capture type A) and a change (Capture type C) return authorization download trigger exists for the same Key, the system generates a Return Authorization Outbound message for both triggers.

Order Management System Setup for the Outbound Return API

Before you can generate return authorization outbound messages, you must perform the necessary Order Management System setup.

Information requiring setup includes:

• System Control Values Related to the Return Out API

• Menu Options Related to the Return Out API

• Periodic Function Related to the Return Out API

Note: Review this information if you are having trouble creating return authorization download (RAD) triggers or generating the Return Authorization Outbound XML Message (CWReturnRAOut) to help you troubleshoot the problem.

System Control Values Related to the Return Out API

System Control Value	Description
Create Return Download Triggers (K28)	Select this field to create return authorization download (RAD) triggers in the Working with Outbound Interface Transactions (WOIT) menu option when a return authorization is created, changed or deleted.
Outbound Interface Trigger File Purge Days (I14)	Enter the number of days to retain records in the Working with Outbound Interface Transactions (WOIT) menu option before purging them. Run the PURGIJT periodic function (program name ILR0026) to delete any records if: Last processed date is less than the current system date by the number of purge days and Status is X Example: Today is 4/07 and you have set this value to 1. Any record whose Last processed date is 4/06 or earlier is purged. You can also use the Purge option at the Work with Outbound Interface Transactions Screen to purge records.

Menu Options Related to the Return Out API

Menu Option	Description
Working with Outbound Interface Transactions (WOIT)	Allows you to review, delete, or reprocess return authorization download (RAD) triggers.
Working with Integration Layer Processes (IJCT)	When active, the Return Authorization Outbound (RETURN_OUT) job creates a Return Authorization Outbound message for each return authorization download trigger in the Working with Outbound Interface Transactions (WOIT) menu option that is in a ready status. For this job, you can define: • Trigger rules; see Return Authorization Outbound Trigger Rules. • The queues where the return authorization outbound message is sent; see Work with Integration Layer Process Queues Screen.

Periodic Function Related to the Return Out API

Periodic Function	Description
Purge IJCT Download (program name ILR0026)	Run this periodic function to purge processed triggers in the Working with Outbound Interface Transactions (WOIT) menu option, based on the Outbound Interface Trigger File Purge Days (I14) system control value: Last processed date is less than the current system date by the number of purge days and Status is X

Return Authorization Outbound: Sample XML Messages

Samples of the Return Authorization Outbound XML Message (CWReturnRAOut) are presented below.

• Return Authorization Outbound: Created Return Authorization

• Return Authorization Outbound: Changed Return Authorization

• Return Authorization Outbound: Deleted Return Authorization

Return Authorization Outbound: Created Return Authorization

A sample of the Return Authorization Outbound XML Message (CWReturnRAOut) that is generated when a return authorization is created is presented below.

<Message source="OROMS" target="cwi" type="CWReturnRAOut" date_created="04282009" time_created="11:44:28">

<RADetail company="7" order_nbr="1558" ship_to_nbr="1" ra_nbr="1" line_nbr="1" qty_to_return="3" qty_returned="3" qty_credited="2" refund_freight="Y" refund_add_charge="Y" return_date="04282009" refund_handling="Y" refund_duty="Y" ret_reason="1" ret_disposition_code="5" item="SKU" item_desc="SKU ITEM DESCRIPTION" sku="BLUE SML WMNS" sku_desc="WOMEN'S SMALL BLUE SKU DESCRIPTION" />

</Message>

Return Authorization Outbound: Changed Return Authorization

A sample of the Return Authorization Outbound XML Message (CWReturnRAOut) that is generated when a return authorization is changed is presented below.

<Message source="OROMS" target="cwi" type="CWReturnRAOut" date_created="04282009" time_created="09:13:23">

<RADetail company="7" order_nbr="1555" ship_to_nbr="1" ra_nbr="1" line_nbr="3" qty_to_return="3" refund_freight="Y" refund_add_charge="Y" refund_handling="Y" refund_duty="Y" ret_reason="1" ret_disposition_code="1" item="SKU" item_desc="SKU ITEM DESCRIPTION" sku="RED SML WMNS" sku_desc="WOMEN'S SMALL RED SKU DESCRIPTION" />

</Message>

Return Authorization Outbound: Deleted Return Authorization

A sample of the Return Authorization Outbound XML Message (CWReturnRAOut) that is generated when a return authorization is deleted is presented below.

For delete return authorization outbound messages, 0 displays in the qty_to_return, qty_returned, and qty_credited tags, indicating the return authorization was deleted.

<Message source="OROMS" target="cwi" type="CWReturnRAOut" date_created="04282009" time_created="08:26:41">

<RADetail company="7" order_nbr="1555" ship_to_nbr="1" ra_nbr="1" line_nbr="1" qty_to_return="0" qty_returned="0" qty_credited="0" />

</Message>

Return Authorization Outbound XML Message (CWReturnRAOut)

 

The return authorization outbound message contains return authorization information to send from Order Management System to another system, such as a warehouse management system. The system generates a separate return authorization outbound message for each RA line.

For more information: See:

• Outbound Return API for an overview.

• Return Authorization Outbound: Sample XML Messages for sample messages.

• XML Messages for a sample of the DTD, schema, and generic sample XML of the Return Authorization Outbound XML message.

Attribute Name	Type	Length	Comments
Message
source	alpha		Identifies the source of the XML message. OROMS indicates the XML message is from Order Management System.
target	alpha		Identifies the target of the XML message.
type	alpha		Identifies the type of information in the XML message. CWReturnRAOut indicates the message contains return authorization download information.
date_created	numeric	8	The date the message was generated, in MMDDYYYY format.
time_created	numeric		The time the message was generated, in HH:MM:SS format.
RADetail
company	numeric	3	A code for the company where the return authorization was processed. From the CMP Company field in the RA Detail table.
order_nbr	numeric	8	The order number associated with the return authorization. From the Order # field in the RA Detail table.
ship_to_nbr	numeric	3	The ship to number associated with the return authorization. From the Ship to # field in the RA Detail table.
ra_nbr	numeric	3	The return authorization number. From the RAH RA# field in the RA Detail table.
line_nbr	numeric	3	The return authorization line number. From the RAD Line # field in the RA Detail table.
qty_to_return	numeric	5	The total number of units of the item authorized for return. For delete return authorization outbound messages, 0 displays in the qty_to_return, qty_returned, and qty_credited tags, indicating the return authorization was deleted. From the RAD Qty to return field in the RA Detail table.
qty_returned	numeric	5	The quantity of the item that the customer has returned to date against the RA line. For delete return authorization outbound messages, 0 displays in the qty_to_return, qty_returned, and qty_credited tags, indicating the return authorization was deleted. From the RAD Qty returned field in the RA Detail table.
qty_credited	numeric	5	The quantity of the item that has been returned, received, and credited. For delete return authorization outbound messages, 0 displays in the qty_to_return, qty_returned, and qty_credited tags, indicating the return authorization was deleted. From the RAD Qty credited field in the RA Detail table.
refund_freight	alpha	1	Indicates whether the system refunds freight to the customer when crediting the return. Valid values are: • Y = Refund freight. • N = Do not refund freight. From the RAD Refund freight field in the RA Detail table.
refund_add_ charge	alpha	1	Indicates whether the system refunds additional charges when crediting the return. If there were negative additional charges billed on the order, refunding them results in adding positive additional charges, or decreasing the net amount of any refund. Valid values are: • Y = Refund additional charges. • N = Do not refund additional charges. From the RAD Refund add’l chgs field in the RA Detail table.
return_date	numeric	8	The date the item was received, in MMDDYYYY format. From the RAD Return date field in the RA Detail table.
refund_handling	alpha	1	Indicates whether the system refunds handling charges when crediting the return. Valid values are: • Y = Refund handling. • N = Do not refund handling. From the RAD Refund handling field in the RA Detail table.
refund_duty	alpha	1	Indicates whether the system refunds duty charges when crediting the return. Valid values are: • Y = Refund duty. • N = Do not refund duty. From the RAD Refund duty field in the RA Detail table.
ret_reason	numeric	3	The reason why the item was returned. Return reason codes are defined in and validated against the Return Reason table; see Establishing Return Reason Codes (WRTR). From the RTR Return reason code field in the RA Detail table.
exchange_reason	numeric	3	The reason why the item was exchanged. Exchange reason codes are defined in and validated against the Exchange Reason table; see Establishing Exchange Reason Codes (WEXR). From the EXR Exchange reason code field in the RA Detail table.
ret_disposition_ code	alpha	2	The return disposition code assigned to the RA line, indicating whether the return updates inventory and the warehouse and location to which the item is returned. Return disposition codes are defined in and validated against the Return Disposition Values table; see Establishing Return Disposition Values (WRDV). From the RTD Code field in the RA Detail table. Note: This field is blank for returns processed through the Order API; see Processing a Return in the Generic Order Interface (Order API) for more information on returns processed through the Order API.
item	alpha	12	The item being returned. From the ITM Number field in the RA Detail table.
item_desc	alpha	40	A description of the item being returned. From the Description field in the Item table.
sku	alpha	14	The SKU of the item being returned. From the SKU Code field in the RA Detail table.
sku_desc	alpha	40	A description of the SKU being returned. From the Description field in the SKU table.
return_id	alpha	15	The return ID assigned to the RA detail line. You can assign a return ID to an RA detail line in Work with Return Authorizations (WRTA) if the Display Return ID Window (L99) system control value is selected. From the Return ID field in the RA Detail table. Available in: 2.0 (release 4.0 of Order Management System).
pick_nbr	numeric	7	The original pick number for the item being returned. From the Control # field in the Invoice Detail table. Note: This information is not available for a misship return. Available in: 2.0 (release 4.0 of Order Management System).
ShipTo The ship to name and address information associated with the original sales invoice defined for the RA detail line. Included only if the Capture Addresses for Invoice (J24) system control value is selected. Note: Ship to information is not available for a misship return. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_prefix	alpha	3	The prefix of the ship to customer on the order. From the Prefix field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_fname	alpha	15	The ship to customer’s first name. From the First name field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_initial	alpha	1	The ship to customer’s middle initial. From the Initial field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_lname	alpha	25	The ship to customer’s last name. From the Last name field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_suffix	alpha	3	The ship to customer’s suffix. From the Suffix in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_company	alpha	30	The ship to customer’s company name. From the Company name in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_address1	alpha	32	The ship to customer’s street address. From the Address line 1 field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_address2	alpha	32	The second address line for the ship to customer’s address. From the Address line 2 field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_address3	alpha	32	The third address line for the ship to customer’s address. From the Address line 3 in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_address4	alpha	32	The fourth address line for the ship to customer’s address. From the Address line 4 field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_apartment	alpha	10	The ship to customer’s apartment code. From the Apartment field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_city	alpha	25	The city on the ship to customer’s address. From the City field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_state	alpha	2	The state code on the ship to customer’s address. From the State field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_state_description	alpha	25	The name of the state. From the Description field in the State table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_zip	alpha	10	The postal code on the ship to customer’s address. From the Zip field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).
ship_to_country	alpha	3	The country code on the ship to customer’s address. From the Country field in the Invoice Address table. Available in: 2.0 (release 4.0 of Order Management System).