Merchandise Locator Searching through JAVA

Merchandise Locator Searching through JAVA

Purpose: Use the merchandise locator integration to request current availability information about an item/SKU in retail stores within a geographic search area or in external warehouses.

Locate version? The integration described in this chapter is used only when the Locate Platform is set to JAVA, so that CWDirect communicates directly with version 5.1 or higher of Locate. See Merchandise Locator and Store Fulfillment API through .NET for information on merchandise locator searching through integration with Locate 2.1 or 2.5 through the cw_locate site.

Informational searching only: When the Locate Platform is set to JAVA, it is not possible to create delivery or pickup orders through the merchandise locator search. However, the Order Broker integration provides the ability to automatically assign backordered items to store locations for fulfillment, as well as fulfilling retail pickup and delivery orders in CWDirect. See the Order Broker Integration for more information.

In this topic:

• Merchandise Locator Process Overview

• Merchandise Locator Setup

• Merchandise Locator Search Window (JAVA integration)

• Merchandise Locator Search Results Screen (JAVA Integration)

• Display Merchandise Locator Search Result Screen (JAVA)

• Merchandise Locator Request/LocateItems Request Message Mapping

• Merchandise Locator Request Message: Sample XML

• LocateItems Request Message: Sample XML

• LocateItems Response/CWMerchLocResponse Message Mapping

• LocateItems Response Message: Sample XML

• LocateItems Response for Virtual Location: Sample XML

• CWMerchLocResponse: Sample XML

Merchandise Locator Process Overview

Overview: A typical process of inquiring on merchandise availability using Locate’s Order Broker module is described below.

Locate version: The process described below can take place when the Locate Platform is set to JAVA, the setting required when integrating directly with Locate 5.1 or higher.

Merchandise locator search:

1. A customer does not want to wait for you to ship an item/SKU from your warehouse and would like to pick it up instead at a nearby store. Alternatively, you or a customer want to check on whether a store location can ship an item that is unavailable in the warehouse.

2. You select the item/SKU for merchandise locator inquiry. This option is available in order entry, order maintenance, and at the Display Item Availability Screen (Reviewing Item Availability).

3. You advance to the Merchandise Locator Search Window (JAVA integration), where you:

• provide or confirm the customer’s geographic location

• provide or confirm the radius to search within (for example, search all stores within 25 miles of the customer’s home)

• whether you are searching for locations that have the item/SKU available for pickup or shipment

4. Once you submit the search:

• The system generates the Merchandise Locator Request/LocateItems Request Message Mapping, and puts the message in a data queue.

• A java job maps the information to Locate’s LocateItems request message, and sends the message to Locate.

• Locate ’s Order Broker uses the rules you have set up for merchandise location to find locations that stock the requested item/SKU and could fulfill an order. The rules you can set up include:

• ranking eligible locations based proximity, available quantity, last order assigned, sales velocity, or numerical ranking

• fulfillment zones that specify which locations are eligible to fulfill orders based on the order’s shipping address

• calculations that you apply to locations (probability rules)

• subtracting orders in certain statuses to calculate the available quantity to promise (reserved quantity)

• obtaining updated available quantities from locations based on the date and time when the information for the item and location were last updated

• Locate ’s Order Broker then sends the LocateItems response message, listing the locations that could fulfill an order for the item/SKU in the requested quantity. The information returned also includes the quantity expected on the next open purchase order and the date.

Virtual location? If the Group Shipment Locations preference is selected in Locate and the search specifies a Fulfillment type of DELIVERY, Locate does not return an actual list of locations; instead, the response includes just the virtual location, indicating that the requested item is available for shipment.

• The java job maps the information in the LocateItems request to the LocateItems Response/CWMerchLocResponse Message Mapping.

5. You advance to the Merchandise Locator Search Results Screen (JAVA Integration), displaying the information returned by Locate.

Merchandise Locator Setup

The setup required for merchandise locator integration is described below.

Locate version: The setup described below is required when the Locate Platform is set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

Merchandise locator settings: Set up the following system control values at the Merchandise Locator Values (I37) screen:

• Use Merchandise Locator (I38): Must be set to Y in order for merchandise locator or store fulfillment functionality to be available in order entry.

• Merchandise Locator Distance Measurement (I39): Specify the distance unit of measure to use for merchandise locator searches. Valid values are:

• K = distances displayed at the Merchandise Locator Search Results Screen (JAVA Integration) are in kilometers

• M = distances displayed at the Merchandise Locator Search Results Screen (JAVA Integration) are in miles

• Default Search Within Radius (I40): Optionally, specify the default number of miles or kilometers (based on the Merchandise Locator Distance Measurement (I39)) for merchandise locator searches. This value defaults at the Merchandise Locator Search Window (JAVA integration), but you can override it.

• Fulfillment Type (M21): Optionally, specify a default fulfillment type of PICKUP or DELIVERY for merchandise locator searches. This value defaults at the Merchandise Locator Search Window (JAVA integration), but you can override it.

Note: The additional system control values at the Merchandise Locator Values (I37) screen are not used for merchandise locator searching with Locate version 5.1 or higher.

Order Broker settings: The following settings from the Order Broker Values (K15) screen are also used for merchandise locator searching:

• Locate Account Name (K49): The name of the Locate database, as specified at the Tenant screen in Locate. This account name is passed as the destination in merchandise locator searching.

• Locate Default Location (K51): The code identifying the CWDirect warehouse that is requesting the merchandise locator search.

• Locate Platform: Must be set to JAVA. See Merchandise Locator and Store Fulfillment API through .NET for information on merchandise locator searching through integration with Locate 2.1 or 2.5 through the cw_locate site.

Note: The Order Broker Include Default Country Orders Only (M29) system control value does not apply to merchandise locator searches.

Properties file settings: See Setup in the cw.properties File for more information on required setup for the Order Broker integration, including merchandise locator searches.

Item and inventory import: Ordinarily, you use the item and inventory import to create records of your items and SKUs in Locate. See Sending Item and Inventory Information to Locate for background, and see Item and Inventory Import Setup for setup information.

Locate setup: Includes:

• Preferences screen

• Location types and locations

• System settings

• Optionally, probability rules and fulfillment zones

See Setting Up Data for the Order Broker Module in the Locate online help for more information.

Merchandise Locator Search Window (JAVA integration)

Purpose: Use this window to check availability for an item across external locations, such as warehouses and stores, through Locate. To search, you need to specify the customer’s location, either by city and state or postal code, the search radius, and the type of order (pickup or delivery).

Address defaults: If you advance to this window in order entry or order maintenance, the customer’s address information defaults. Also, if you have overridden the information at this window in order entry or order maintenance, the system continues to default the override information during the current session for the order. For example, if you perform a search using the customer’s work address for an item/SKU, and then select another item/SKU for a search while working with the same order, the customer’s work address defaults.

Locate version: The following description of this window is based on the Locate Platform being set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

How to display this window: Enter 15 next to an item at the:

• Work with Order Lines Screen (Adding Items to the Order)SKU Scan Screen

• Work with Order/Detail Screen

• Scan Order Lines Screen

• Display Item Availability Screen (Reviewing Item Availability)

Additional edits:

• This option is not available from the Display Item Availability Screen (Reviewing Item Availability) if you have already selected a quantity of the item to add to the order. Instead, the system displays an error message: Option not allowed since item already selected.

• The Use Merchandise Locator (I38) system control value must be set to Y. Otherwise, the system displays an error message: Merchandise Locator is not enabled.

• The item’s Locate elig (Locate eligible) field must be set to Y. Otherwise, the system displays an error message: Item not Locate eligible.

Merchandise Locator Search

Item . : KABNOSKU

TEST ITEM

Enter postal code OR city, state and country:

Postal code .

Address . . .

City . . . .

State . . . .

Country . . . USA

Search Within . . 25 (Miles)

Fulfillment Type PICKUP (Delivery, Pickup)

Enter=Search F12=Cancel

Field	Description
Item	The item selected at the previous screen. The SKU information, if any, is to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, one 14-position field (full SKU) or three 4-position fields (split SKU); display-only.
Item description	The description of the item. Even if the item has SKU’s, the item description is displayed. Alphanumeric, 40 positions; display-only.
Note: If you advanced to this window from order entry or order maintenance, the customer’s address information defaults.
Postal code	The customer’s zip or postal code, to serve as the central point for the search radius. For example, if the Search within field is set to 25 miles, the search includes stores within 25 miles of this postal code. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Note: Your entry in this field is not validated against the Zip/City/State file. Alphanumeric, 10 positions; required if you do not enter a city and state.
Address	The customer’s street address, to serve as the central point for the search radius. Not used for merchandise locator searching if you specify a Postal code. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 32 positions; optional.
City	The customer’s city, to serve as the central point for the search radius. Not used for merchandise locator searching if you specify a Postal code. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 25 positions; required if you do not enter a postal code.
State	The customer’s state or province, to identify the location of the city. Not used for merchandise locator searching if you specify a Postal code. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Note: State is not required if the country’s Require state flag is set to N. See Setting Up the Country File (WCTY) for more information. However, Locate does not currently support proximity searches in any countries besides the United States and Canada. Alphanumeric, 2 positions; required if there is no postal code specified and if the country’s Require state flag is set to N.
Country	The customer’s country. The country defaults from the customer address if you advanced to this window from order entry or order maintenance; otherwise, it defaults from the Default Country for Customer Address (B17) system control value. Defined in and validated against the Country file; see Setting Up the Country File (WCTY) for more information. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Note: The Order Broker Include Default Country Orders Only (M29) system control value does not apply to merchandise locator searches. Alphanumeric, 2 positions; required.
Search within	Indicates the search radius, in the unit of measure indicated, to search within for the selected item. The search radius defaults from the Default Search Within Radius (I40) system control value, but you can override it. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Note: The distance unit of measure specified with the Merchandise Locator Distance Measurement (I39) system control value displays to the right. Valid values are Kilometers and Miles. Numeric, 5 positions; required.
Fulfillment type	Indicates whether to search for locations where the customer can pick up the item, or that can ship the item. Defaults from the Fulfillment Type (M21) system control value, but you can override the default. Valid values are: • DELIVERY = Search for locations that could ship the item to the customer. Only locations that are flagged in Locate as Shipping Available, that stock the item, and that otherwise meet the search criteria are included in the search results. • PICKUP = Search for locations where the customer could pick up the item. Only locations that are flagged in Locate as Pickup Available, that have the item available in stock, and that otherwise meet the search criteria are included in the search results. Virtual location? If the Group Shipment Locations preference is selected in Locate and the search specifies a Fulfillment type of DELIVERY, Locate does not return an actual list of locations; instead, the response includes just the virtual location, indicating that the requested item is available for shipment. Alphanumeric, 8 positions; required.

Completing this window:

• If they have not already defaulted, indicate the postal code or the city and state to serve as the central point for the search radius.

• Optionally, override the Search within radius to a different distance.

• Optionally, override the Location type, or enter a Location type if it has not defaulted.

• Press Enter. The system communicates with Locate, as described under the Merchandise Locator Process Overview. When the system receives the response from Locate, you advance to the Merchandise Locator Search Results Screen (JAVA Integration).

Merchandise Locator Search Results Screen (JAVA Integration)

Purpose: Use this screen to review an item’s availability in external warehouses and stores. You can also use this screen to review more information about an external location.

Locate version: The following description of the screen is based on the Locate Platform being set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

How to display this screen: Complete the Merchandise Locator Search Window (JAVA integration) and press Enter.

Troubleshooting: Possible error messages:

• Availability information is not accessible at this time: Possible reasons:

• Communication between CWDirect and Locate is not active, or because Locate could not identify the search location based on the information sent in the search request (for example, it has no record of the provided zip code). See the Locate Operations Guide for more information.

• The Locate Account Name (K49) system control value is not set correctly.

• The Locate System (K50) system control value is not set correctly.

• The Locate Default Location (K51) system control value is not set correctly.

• The item is flagged as Locate elig (Locate eligible), but has not yet been exported to Locate.

• The selected item is not sold in the requested locations.Possible reasons:

• None of the locations within the search area have the item/SKU in stock, or support the requested fulfillment type. You can press F7 to change the search location, distance to search within, or fulfillment type.

• Cannot identify customer location. Possible reason: The customer address information provided in the merchandise locator request was invalid or incomplete. This could occur if, for example, you entered a Canadian address, but the database used to identify customer locations in Locate includes only U.S. addresses. Locate currently supports only United States or Canadian addresses.

For more information: See the LocateItems Response/CWMerchLocResponse Message Mapping for the actual information used to populate the information on this screen.

MLX0003 DISPLAY Merchandise Locator Search Results 11/19/14 16:27:42

EZK Mail Order

Locations closest to: 1234 MAIN STREET, NATICK, MA 01760 USA

Radius. . . . . . . : 25 Miles

Item . . : CLIP1234

JUMBO HAIR CLIP SILVER

Opt Dist Location Avail Open PO Next PO

Type options, press Enter.

5=Display

13.21 Store 20 EZK2 POS Westborough 15 50 11/30/14

Westborough, MA 01581 US

25.34 Store 10 EZK2 POS Worcester 2- 0

Worcester, MA 01602 US

F3=Exit F7=Search Again F12=Cancel

Field	Description
Locations closest to	The address information provided at the Merchandise Locator Search Window (JAVA integration). This information could be just a postal code, a city and state, or could include additional information such as the street address. The information is truncated if it exceeds the space allowed on this screen. The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 55 positions; display-only.
Radius	The Search within radius selected at the Merchandise Locator Search Window (JAVA integration). This distance can be in either kilometers or miles, depending on the setting of the Merchandise Locator Distance Measurement (I39). The search radius applies only to locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Numeric, 5 positions; display-only.
Item	The item selected for search. The SKU information, if any, displays to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, one 14-position field (full SKU) or three 4-position fields (split SKU); display-only.
Item description	The description of the item. Even if the item has SKU’s, the item description is displayed. Alphanumeric, 40 positions; display-only.
Dist	The distance from the search location in the Merchandise Locator Distance Measurement (I39). This distance might be approximate, depending on the actual criteria used to search (for example, postal code or city), and does not represent an actual driving distance. Distance is displayed only if proximity rules apply to the location. Typically, proximity rules do not apply to warehouses. In this situation, no distance is displayed. Virtual location: The distance is blank if the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item. See the Merchandise Locator Process Overview for background. In this case, the Location indicated is: Available to be shipped from a store. See the Merchandise Locator Process Overview for background. Numeric, 7 positions with a 2-place decimal.
Location	The description and address of the location where the item/SKU is available, consisting of: • description • city • state • postal code • country This information is from the response sent from Locate, not from the information you set up through Working with Store Cross References (WSXR). Virtual location? If the Group Shipment Locations preference is selected in Locate and the search specifies a Fulfillment type of DELIVERY, Locate does not return an actual list of locations; instead, the response includes just the virtual location, indicating that the requested item is available for shipment. In this case, the Location indicated in the search results is: Available to be shipped from a store. In this case, the Distance, Avail, Open PO, and Next PO fields are blank, and no address is indicated. See the Merchandise Locator Process Overview for background. Description: alphanumeric, 40 positions; display-only. City: alphanumeric, 25 positions; display-only. State: alphanumeric, 2 positions; display-only. Postal code: alphanumeric, 10 positions; display-only. Country: alphanumeric, 3 positions; display-only.
Avail	The available quantity of the item/SKU reported in the LocateItems response for this location. Depending on your settings within Locate, this quantity may be approximate, calculated based on probability rules, or reduced by a reserved quantity for the location. A negative available quantity is possible when the Fulfillment type is DELIVERY and the location is flagged in Locate as supporting backorders. Virtual location? The available quantity is blank if the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item. See the Merchandise Locator Process Overview for background. In this case, the Location indicated is: Available to be shipped from a store. Numeric, 7 positions; display-only.
Open PO	The quantity of the item/SKU reported on open purchase orders for this location. Virtual location? The open purchase order quantity is blank if the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item. See the Merchandise Locator Process Overview for background. In this case, the Location indicated is: Available to be shipped from a store. Numeric, 7 positions; display-only.
Next PO	The date when the next purchase order for this item/SKU is due to be received at this location. Virtual location? The next purchase order date is blank if the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item. See the Merchandise Locator Process Overview for background. In this case, the Location indicated is: Available to be shipped from a store. Numeric, 6 positions (MM/DD/YY format); display-only.

Option	Procedure
Display a location	Enter 5 next to a location to advance to the Display Merchandise Locator Search Result Screen (JAVA).
Search again	Press F7 to return to the Merchandise Locator Search Window (JAVA integration).

Display Merchandise Locator Search Result Screen (JAVA)

Purpose: Use this screen to review additional details about a location found through a merchandise locator search. You cannot make any changes on this screen.

Note: The address components, such as postal code, country, and phone number, are provided by Locate and might not be formatted or validated at this screen the same way as they are for data stored in CWDirect. For example, the country code might be different, and the information might be in upper and lower case.

Locate version: The following description of the screen is based on the Locate Platform being set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

Virtual location? This screen does not display any additional information if the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item. See the Merchandise Locator Process Overview for background. In this case, the Location indicated is: Available to be shipped from a store.

How to display this screen: Enter 5 next to a location at the Merchandise Locator Search Results Screen (JAVA Integration).

MLX0004 DISPLAY Dsp Merchandise Locator Search Result 11/19/14 16:44:04

EZK Mail Order

Item . . . : CLIP12345

JUMBO HAIR CLIP SILVER

Distance . : 25.34 Miles

Location . : Store 10 Worcester

1234 Main Street

2nd floor left

Worcester, MA 01602 US

5081111111

Available. : 2-

Open PO . : 0

Next PO . :

F3=Exit F12=Cancel

Field	Description
Item	The item selected for search. The SKU information, if any, displays to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, one 14-position field (full SKU) or three 4-position fields (split SKU); display-only.
Description	The description of the item. Even if the item has SKU’s, the item description is displayed. Alphanumeric, 40 positions; display-only.
Distance	The distance from the search location in the Merchandise Locator Distance Measurement (I39). This distance might be approximate, depending on the actual criteria used to search (for example, postal code or city), and does not represent an actual driving distance. Actual distance is provided only for locations that use proximity rules. Typically, you would set up Locate so that proximity rules apply to stores only and not warehouses. Otherwise, the distance is .00 miles or kilometers. Numeric, 7 positions with a 2-place decimal; display-only.
Location	The description and address of the location where the item/SKU is available, consisting of: • description • street address (up to three lines) • city • state • postal code • country • phone number Virtual location? If the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item, the Location indicated is: Available to be shipped from a store. See the Merchandise Locator Process Overview for background. Description: alphanumeric, 40 positions; display-only. Street: alphanumeric, 40 positions each; display-only. City: alphanumeric, 25 positions; display-only. State: alphanumeric, 2 positions; display-only. Postal code: alphanumeric, 10 positions; display-only. Country: alphanumeric, 3 positions; display-only. Phone number: alphanumeric, 14 positions; display-only.
Available	The available quantity of the item/SKU reported in the LocateItems Response/CWMerchLocResponse Message Mapping for this location. Depending on your settings within Locate, this quantity may be approximate, calculated based on probability rules, or reduced by a reserved quantity for the location. A negative available quantity is possible when the Fulfillment type is DELIVERY and the location is flagged in Locate as supporting backorders. Virtual location? If the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item, the available quantity indicated is 0. See the Merchandise Locator Process Overview for background. Numeric, 7 positions; display-only.
Open PO	The quantity of the item/SKU reported on open purchase orders for this location. Virtual location? If the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item, the open purchase order quantity indicated is 0. See the Merchandise Locator Process Overview for background. Numeric, 7 positions; display-only.
Next PO	The date when the next purchase order for this item/SKU is due to be received at this location. Virtual location? If the response from Locate includes the virtual location, indicating that the item is available for shipment without listing any of the actual locations that might fulfill an order for the item, the next purchase order quantity indicated is 0. See the Merchandise Locator Process Overview for background. Numeric, 6 positions (MM/DD/YY format); display-only.

Merchandise Locator Request/LocateItems Request Message Mapping

Overview: The system generates the CWMerchLocRequest message when you complete the Merchandise Locator Search Window (JAVA integration) and press Enter. The Java job then takes this message and maps it to Locate’s LocateItems request message. The following table describes how the job maps data from the CWDirect message to the Locate message.

Locate version: The following mapping occurs the Locate Platform being set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

Sample messages: See Merchandise Locator Request Message: Sample XML and LocateItems Request Message: Sample XML.

For more information: See Merchandise Locator Process Overview for an overview, and see the.Merchandise Locator Request XML Message (CWMerchLocRequest) (.NET) for a listing of the supported elements and attributes of the CWMerchLocRequest message.

CWDirect Attribute Name (CWMerchLoc Request)	Type	Locate Attribute Name (LocateItems request)	Comments
N/A	numeric	version	From the Message version (Broker) in the cw.properties file. Typically set to 5.1. See Order Broker Setup for background.
source	alpha	source	Set to CWDirect. Informational only.
locate_acct Note: This attribute is used only for the JAVA integration, and is not included in the standard CWMerchLocRequest message.	alpha	destination	From the Locate Account Name (K49) system control value.
fulfillment_type Note: This attribute is used only for the JAVA integration, and is not included in the standard CWMerchLocRequest message.	numeric	fulfillment_type	From the Fulfillment type specified at the Merchandise Locator Search Window (JAVA integration). Defaults from the Fulfillment Type (M21) system control value. Valid values are: • DELIVERY = Search for locations that could ship the item to the customer • PICKUP = Search for locations where the customer could pick up the item Virtual location? If the Group Shipment Locations preference is selected in Locate and the search specifies a Fulfillment type of DELIVERY, Locate does not return an actual list of locations; instead, the response includes just the virtual location, indicating that the requested item is available for shipment.
request_quantity	numeric	qty	The requested quantity of the item. The CWMerchLocRequest message does not include this quantity when you perform the merchandise locator search from the Display Item Availability Screen (Reviewing Item Availability), so in this case the qty in the LocateItems request is set to 1.
item_number and sku	alpha	item_id	The code identifying the requested item. The item and SKU codes are concatenated for a SKU’d item.
system_cd Note: This attribute is used only for the JAVA integration, and is not included in the standard CWMerchLocRequest message.	alpha	system_cd	From the Locate System (K50) system control value.
location_cd Note: This attribute is used only for the JAVA integration, and is not included in the standard CWMerchLocRequest message.	alpha	location_cd	From the Locate Default Location (K51) system control value.
address_line_1	alpha	address1	The street address specified at the Merchandise Locator Search Window (JAVA integration). The sold-to customer’s first address line defaults at this window, but you can override it. Even if the customer’s address includes additional address lines, the message includes only the first line.
city	alpha	city	The city specified at the Merchandise Locator Search Window (JAVA integration). The sold-to customer’s city defaults at this window, but you can override it.
state	alpha	province	The state specified at the Merchandise Locator Search Window (JAVA integration). The sold-to customer’s state defaults at this window, but you can override it.
postal	alpha	postal	The postal code specified at the Merchandise Locator Search Window (JAVA integration). The sold-to customer’s postal code defaults at this window, but you can override it.
country	alpha	country	The country specified at the Merchandise Locator Search Window (JAVA integration). The sold-to customer’s country defaults at this window, but you can override it.
within_distance	numeric	distance	The maximum distance that a location can be from the customer’s address and still be included in the search. For example, if the maximum distance is 25 miles, then only stores and warehouses within 25 miles of the customer’s address should be included in the search. Note: Distance is approximate, and calculated based on the customer’s postal code.
miles_kilometers	alpha	unit	From the Merchandise Locator Distance Measurement (I39) system control value. Indicates the unit of measure of the search distance. Valid values are: K = kilometers M = miles

Merchandise Locator Request Message: Sample XML

A sample of the merchandise locator request generated when you complete the Merchandise Locator Search Window (JAVA integration) is presented below.

</MerchLocRequest>

</Message>

LocateItems Request Message: Sample XML

A sample of the LocateItems request message, generated by the Java job based on the information in the merchandise locator request, is presented below. The Java job sends this message to Locate for processing by the Order Broker.

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns2:LocateItems xmlns:ns2="http://microsretail.com/Locate">

<ns2:location_request_message><message_header original_request_id="" message_type="" xaction_response="" xaction_type="INSERT">

<source>CWDirect</source>

<destination>LOCATE</destination>

</message_header>

<message_body>

<items>

</items>

<store_location system_cd="27" location_cd="2"></store_location>

<address1>1234 MAIN TREET</address1>

<city>NATICK</city>

</address>

<range>

</range>

</message_body>

</ns2:location_request_message>

</ns2:LocateItems>

</S:Body>

</S:Envelope>

LocateItems Response/CWMerchLocResponse Message Mapping

Overview: As described in the Merchandise Locator Process Overview, the Java job maps the information in the LocateItems response received from Locate into the CWMerchLocResponse message, and then the system loads the information from the response into the Merchandise Locator Work file, and the Merchandise Locator Search Results Screen (JAVA Integration) displays the information.

Locate version: The following description of the message is based on the Locate Platform being set to JAVA, the setting required when integrating directly with version 5.1 or higher of Locate.

Sample messages: See LocateItems Response Message: Sample XML, LocateItems Response for Virtual Location: Sample XML, and CWMerchLocResponse: Sample XML.

For more information: See Merchandise Locator Process Overview for an overview, and see the Merchandise Locator Request XML Message (CWMerchLocRequest) (.NET) for a listing of the supported elements and attributes of the CWMerchLocResponse message.

Locate Attribute Name (LocateItems response)	Type	CWDirect Attribute Name (CWMerchLoc Response)	Comments
response_cd	numeric	response	Indicates that inventory information is not available for the item/SKU. Possible response values in the CWMerchLocResponse message are: OK = The LocateItems response includes one or more eligible locations or the virtual location. This response indicates that the response_cd in the LocateItems response was blank (" ").
			I = No eligible locations within the search area stock the item/SKU. This response could indicate that the LocateItems response included a response_cd of 1003 or 1011. The Merchandise Locator Search Results Screen (JAVA Integration) displays a message: Selected item not sold in requested locations. C = The customer address information provided in the request message was invalid or incomplete. This response could indicate that the LocateItems response included a response_cd of 1012. The Merchandise Locator Search Results Screen (JAVA Integration) displays a message: Cannot identify customer location.
			N = The requested item/SKU does not exist in Locate, typically because it has not yet been imported from CWDirect through the import process described in Sending Item and Inventory Information to Locate. This response could indicate that the LocateItems response included a response_cd of 1002. The Merchandise Locator Search Results Screen (JAVA Integration) displays a message: Availability is not accessible at this time. Note: The Merchandise Locator Search Results Screen (JAVA Integration) also displays the Availability is not accessible at this time message when CWDirect does not receive a response from Locate, or when the response includes a more basic error, such as when the system or location is invalid or when Locate does not send a response. When the response is not OK, additional information is not displayed at the Merchandise Locator Search Results Screen (JAVA Integration).
system_cd	alpha	location_ system_id	The system associated with the location that could fulfill an order for the item. This code is not displayed at the Merchandise Locator Search Results Screen (JAVA Integration). Set to V for the virtual location. See Merchandise Locator Process Overview for background.
location_cd	alpha	location_id	The code identifying the location that could fulfill an order for the item. This code is not displayed at the Merchandise Locator Search Results Screen (JAVA Integration). Set to V for the virtual location. See Merchandise Locator Process Overview for background.
distance	numeric	distance	The location’s distance from the customer’s location, as entered at the Merchandise Locator Search Window (JAVA integration). The distance in the CWMerchLocResponse is formatted with an implied decimal. Note: Distance is approximate, and calculated based on the customer’s postal code. Blank for the virtual location. See Merchandise Locator Process Overview for background.
locationname	alpha	location_desc	The name of the location that could fulfill an order for the item. This information is from the response sent from Locate, not from the information you set up through Working with Store Cross References (WSXR). The locationname is Available for Shipment for the virtual location. See Merchandise Locator Process Overview for background.
address1	alpha	address_line_1	The street address of the location. Not returned for the virtual location.
city	alpha	city	The city for the location. Not returned for the virtual location. See Merchandise Locator Process Overview for background.
province	alpha	state	The state or province code for the location. Not returned for the virtual location. See Merchandise Locator Process Overview for background.
postal	alpha	postal	The zip or postal code for the location. Not returned for the virtual location. See Merchandise Locator Process Overview for background.
country	alpha	country	The country code for the location. Not returned for the virtual location. See Merchandise Locator Process Overview for background.
phone1	alpha	phone_nbr	The phone number for the location. Not returned for the virtual location. See Merchandise Locator Process Overview for background.
available_qty	numeric	available	The available quantity of the item/SKU reported in the LocateItems response for this location. Depending on your settings within Locate, this quantity may be approximate, calculated based on probability rules, or reduced by a reserved quantity for the location. A negative available quantity is possible when the Fulfillment type is DELIVERY and the location is flagged in Locate as supporting backorders. Blank for the virtual location. See Merchandise Locator Process Overview for background.
next_po_qty	numeric	open_po	The quantity of the item/SKU reported on open purchase orders for this location. Blank for the virtual location. See Merchandise Locator Process Overview for background.
po_dt	numeric	next_po_date	The date when the next purchase order for this item/SKU is due to be received at this location. Blank for the virtual location. See Merchandise Locator Process Overview for background.

LocateItems Response Message: Sample XML

A sample of the LocateItems response message, generated when Locate receives the LocateItems request message is displayed below. The Java job maps the information in this message to the CWMerchLocResponse message.

See LocateItems Response/CWMerchLocResponse Message Mapping for mapping information.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:LocateItemsResponse xmlns:ns2="http://microsretail.com/Locate">

<location_response_message>

<message_header xaction_response="OK" xaction_type="INFO">

<source>LOCATE</source>

<destination>CWDirect</destination>

</message_header>

<message_body request_id="81751">

<items>

<locations_lu location_cd="20" system_cd="EZK2_POS" distance="13.21" distance_unit="M" available_qty="-20" next_po_qty="50" po_dt="2014-11-30" fulfillment_type="DELIVERY"/>

<locations_lu location_cd="10" system_cd="EZK2_POS" distance="25.34" distance_unit="M" available_qty="10" next_po_qty="0" po_dt="" fulfillment_type="DELIVERY"/>

</item>

</items>

<locationname>Store 20 EZK2 POS Westborough</locationname>

<address1>5678 Main Street</address1>

<city>Westborough</city>

</address>

</location>

<locationname>Store 10 Worcester</locationname>

<address1>1234 Main Street</address1>

<address2>2nd floor left</address2>

<city>Worcester</city>

</address>

</location>

</locations>

</message_body>

</location_response_message></ns2:LocateItemsResponse>

</soap:Body>

</soap:Envelope>

LocateItems Response for Virtual Location: Sample XML

A sample of the LocateItems response returned when the Group Shipment Locations preference is selected in Locate, the Fulfillment type is DELIVERY, and the item is available within the search criteria is presented below.

See LocateItems Response/CWMerchLocResponse Message Mapping for mapping information.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:LocateItemsResponse xmlns:ns2="http://microsretail.com/Locate">

<location_response_message>

<message_header xaction_response="OK" xaction_type="INFO">

<source>LOCATE</source>

<destination>CWDirect</destination>

</message_header>

<message_body split_order="No" request_id="81773">

<items>

<locations_lu location_cd="V" system_cd="V" distance="" distance_unit="M" available_qty="" next_po_qty="" po_dt="" fulfillment_type="DELIVERY"/>

</item>

</items>

<locationname>Available for Shipment</locationname>

</address>

</location>

</locations>

</message_body>

</location_response_message>

</ns2:LocateItemsResponse>

</soap:Body>

</soap:Envelope>

CWMerchLocResponse: Sample XML

A sample of the CWMerchLocResponse message, generated when CWDirect receives the LocateItems response message, is displayed below. The Merchandise Locator Search Results Screen (JAVA Integration) and the Display Merchandise Locator Search Result Screen (JAVA) display information from this message.

See LocateItems Response/CWMerchLocResponse Message Mapping for information on how the information in this message maps from the LocateItems response message.

</MerchLocResponses>

</Message>

Merchandise Locator and Store Fulfillment API through .NET

Contents

SCVs

Search

Glossary

Reports

Solutions

XML

Index

Generic Customer Inquiry (Search) API

ST01_11b CWDirect 18.0.x 2018 OTN