5 Retail Location Requests
This chapter provides developers with request formats for retail location requests sent to the Customer Engagement server. The following requests are covered in this chapter:
Note:
Do not use single quotes (apostrophes) in the DisplayName or AttributeValue fields. Using single quotes will cause parsing problems which may result in incorrect data.
The length of the Retail Location ID (1-12 characters) must be set at the time of installation and not changed. Changing the length of the Location ID after installation may result in erroneous data and errors.
Note:
Oracle recommends that the contact details for a location (for example, email address or phone) identify the physical store rather than an individual.
Location Attributes
Location attributes provide a flexible way for retailers to customize the location database and describe individual locations. Location attributes are added or updated according to the following rules:
-
When updating location attributes, all old values are deleted and the new value(s) added in their place. A new attribute cannot simply be added to the list of old ones, it must be sent as part of the entire list.
-
If an update request contains an empty value tag in the
StoreAttributesection, all current values in the database for that attribute are deleted. -
Attribute types must be defined through Attribute Definition prior to processing. Any add/update request containing an unconfigured attribute type will return an
UNKNOWN_ATTRIBUTE_TYPEerror and the add/update will be rejected.Note:
See the Customer Engagement User Guide for more information about Attribute Definition.
-
Data types are enforced during the location add or location update. Logical can only be Yes/No, Number must be numeric, etc. If an incorrect format is used, an error will be returned, and the location add/update will be rejected.
-
If the attribute type is List and a value which is not defined in the list is provided in a location add/update, the add/update request will be rejected (failed).
-
A Unique attribute type defines whether Customer Engagement can accept more than one attribute for that type per location, or, whether only one attribute can be provided (unique).
For example: Location’s average sales amount:
-
Unique = Yes - Only one amount can be specified.
-
Unique = No - More than one amount can be specified.
-
Add Retail Location
The purpose of this action is to add a new retail location to the database. Location attributes can also be added for the retail location.
Note:
If the RetailLocationID specified in the request already exists in the database, the request will be treated like an Update Retail Location request (see Update Retail Location).
Requirements/Restrictions
The minimum data elements/attributes that must be included in order to add a retail location is the RetailLocationID.
Location attributes describe a particular feature of a location. The attribute name is the type, or category, of the attribute. The value is the descriptive part of the name-value pair and is related to the location itself. Each location can have as many attributes as necessary.
Customer Engagement allows multiple values for an attribute name. To configure multiple attribute values for an attribute name, include multiple <AttributeValue> subelements within the <StoreAttribute> element. For example:
<StoreAttribute name="DOORCOLOR"> <AttributeValue>blue</AttributeValue> <AttributeValue>red</AttributeValue></StoreAttribute>
Customer Engagement does not do any checking on the attribute name or value to ensure consistency; therefore, it is important that you be consistent in your use of both the attribute name and value. If you are not consistent, later queries and searches will not return the desired results.
Fields
The elements in the table below are the elements/attributes that may be used in an Add Retail Location request. The sample request shows the placement of these elements/attributes. Not all of these elements/attributes have to be used in any one request.
| XML Tag | Comments |
|---|---|
|
<RetailLocation FranchiseLocationFlag=" " |
FranchiseLocationFlag: True or False. Indicates whether the retail location is a franchise. |
|
Action="AddLocation"> <RetailLocationID> |
(required) Location ID. Can be 1-12 characters, depending upon the length defined by the organization’s configuration. See the Customer Engagement Implementation Guide for more information. |
|
<CreateUser> |
User performing the request. |
|
<StoreNumber> |
Location number. |
|
<AddressLine1> |
First line of the address. |
|
<AddressLine2> |
Second line of the address. |
|
<AddressLine3> |
Third line of the address. |
|
<AddressLine4> |
Fourth line of the address. |
|
<City> |
City |
|
<State> |
State in USA, province in Canada. |
|
<PostalCode> |
Postal/Zip code. |
|
<Country> |
|
|
<County> |
County or Parish. |
|
<DisplayName> |
Name for retail location that is displayed. Do not use single quotes (apostrophes). |
|
<FranchiseID> |
Name or ID of the franchise. Do not use single quotes (apostrophes). |
|
<EmailAddress> |
Email address for the location. |
|
<UserOrganization> |
User Organization the location is associated with. |
|
<StoreAttribute name=" "> |
Name of the location attribute. |
|
<AttributeValue> |
The value of the attribute; must be of the type defined for the attribute. |
Note:
Oracle recommends that the contact details for a location (for example, email address or phone) identify the physical store rather than an individual.
Example
An AddLocation request should appear similar to the example below. The location data included will vary according to each particular request.
If more than one location is being added, there should be multiple <RetailLocation> blocks. in the batch file.
<?xml version="1.0" encoding="UTF-8"?><RetailLocations> <RetailLocation FranchiseLocationFlag="True" Action="AddLocation"> <RetailLocationID><LOCATION_ID></RetailLocationID> <CreateUser><USERID></CreateUser> <StoreNumber><STORE_NUMBER</StoreNumber> <AddressLine1><ADDRESS_EXAMPLE></AddressLine1> <AddressLine2></AddressLine2> <AddressLine3></AddressLine3> <AddressLine4></AddressLine4> <City><CITY></City> <State>OH</State> <PostalCode>44139</PostalCode> <Country>USA</Country> <County>Cuyahoga</County> <DisplayName><LOCATION_DISPLAY_NAME></DisplayName> <FranchiseID><FRANCHISE_ID></FranchiseID> <EmailAddress><USERID>@<TNS_ALIAS></EmailAddress> <UserOrganization><ORGANIZATION_NAME></UserOrganization> <StoreAttribute name="Outlet-Location"> <AttributeValue>false</AttributeValue> </StoreAttribute> <StoreAttribute name="Additional-Departments"> <AttributeValue>Bakery</AttributeValue> <AttributeValue>Florist</AttributeValue> <AttributeValue>Beer - Wine</AttributeValue> </StoreAttribute> <StoreAttribute name="Location"> <AttributeValue>OH</AttributeValue> </StoreAttribute> </RetailLocation></RetailLocations>
Note:
In batch processing, AddLocation, UpdateLocation, and RemoveLocation actions can be included in the same file as long as each action is in a separate <RetailLocation> section and the actions are not on the same location.
Batch Processing Errors
The following table contains a list of errors that may occur and possible causes:
| Error | Cause |
|---|---|
|
ILLEGAL_RETAIL_TRANSACTION_ID |
The retail location data specified does not match the organization's configured parameters. |
|
INVALID_ATTRIBUTE_VALUE |
Invalid data based on attribute type. For example, characters included in a value for a numeric attribute. |
|
INVALID_DATE_FORMAT |
The data in a date field is not valid date information. |
|
INVALID_EMAIL_ADDRESS |
The retail transaction data specified does not match the organization's configured parameters. |
|
MULTIPLE_VALUES_ON_UNIQUE_ATTRIBUTE_TYPE |
Email address is incorrectly formatted. |
|
RETAIL_LOCATION_ID_INVALID |
The request includes multiple values for an attribute defined as unique. |
|
RETAIL_LOCATION_ID_UNSPECIFIED |
No Location ID specified. |
|
UNKNOWN_ATTRIBUTE_TYPE |
Attribute type not found. |
|
VALUE_NOT_IN_ENUMERATED_ATTRIBUTE_TYPE_VALUES |
The value entered for an attribute is not among the possible enumerated values. |
Batch File Response
Success
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Rejected
Each <RetailLocation> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
If there are any failures, the Batch Import Review pages can be used to determine the reason for the failure (see Batch Import Review).
Update Retail Location
The purpose of this action is to update a retail location in the database.
Requirements/Restrictions
The minimum data elements/attributes that must be included to make a valid request are the (required) RetailLocationID and any elements that need to be updated.
The following list are the possible location attribute actions:
-
If the attribute name included in the request already exists for the location in the database, the value in the database will be replaced by the value in the request.
-
If the attribute name does not exist for the location, it will be added.
-
If the attribute name is included with a blank value, the location attribute will be removed from the location.
Fields
The elements in the table below are the elements/attributes that may be used in an Update Retail Location request. The sample request shows the placement of these elements/attributes. A request does not need to include every element or attribute.
| XML Tag | Comments |
|---|---|
|
<RetailLocation FranchiseLocationFlag=" " |
FranchiseLocationFlag: True or False. Indicates whether the retail location is a franchise. |
|
Action="UpdateLocation"> <RetailLocationID> |
(required) Location ID. Can be 1-12 characters, depending upon the length defined by the organization’s configuration. See the Customer Engagement Implementation Guide for more information. |
|
<UpdateUser> |
User performing the request. |
|
<StoreNumber> |
Location number. |
|
<AddressLine1> |
First line of the address. |
|
<AddressLine2> |
Second line of the address. |
|
<AddressLine3> |
Third line of the address. |
|
<AddressLine4> |
Fourth line of the address. |
|
<City> |
City |
|
<State> |
State in USA, province in Canada. |
|
<PostalCode> |
Postal/Zip code. |
|
<Country> |
|
|
<County> |
County or Parish. |
|
<DisplayName> |
Name for retail location that is displayed. Do not use single quotes (apostrophes). |
|
<FranchiseID> |
Name or ID of the franchise. Do not use single quotes (apostrophes). |
|
<EmailAddress> |
Email address for the location. |
|
<UserOrganization> |
User Organization the location is associated with. |
|
<StoreAttribute name=" "> |
Name of the location attribute. |
|
<AttributeValue> |
The value of the attribute; must be of the type defined for the attribute. |
Note:
Oracle recommends that the contact details for a location (for example, email address or phone) identify the physical store rather than an individual.
Note:
If the RetailLocationID specified in the request does not exist in the database, the request will be treated like an Add Retail Location request (see Add Retail Location).
Example
An UpdateLocation request should appear similar to the example below. The location data included will vary according to each particular request.
If more than one location is being updated, there should be multiple <RetailLocation> blocks in the batch file.
<?xml version="1.0" encoding="UTF-8"?><RetailLocations> <RetailLocation FranchiseLocationFlag="True" Action="UpdateLocation"> <RetailLocationID><LOCATION_ID></RetailLocationID> <UpdateUser><USERID></UpdateUser> <StoreNumber><STORE_NUMBER></StoreNumber> <AddressLine1><ADDRESS></AddressLine1> <AddressLine2></AddressLine2> <AddressLine3></AddressLine3> <AddressLine4></AddressLine4> <City>Solon</City> <State>OH</State> <PostalCode>44139</PostalCode> <Country>USA</Country> <County>Cuyahoga</County> <DisplayName><LOCATION_NAME></DisplayName> <FranchiseID><FRANCHISE_ID>/FranchiseID> <EmailAddress><USERID>@<TNS_ALIAS></EmailAddress> <UserOrganization><ORGANIZATION></UserOrganization> <StoreAttribute name="Outlet-Location"> <AttributeValue>false</AttributeValue> </StoreAttribute> <StoreAttribute name="Additional-Departments"> <AttributeValue>Bakery</AttributeValue> <AttributeValue>Florist</AttributeValue> <AttributeValue>Beer - Wine</AttributeValue> </StoreAttribute> <StoreAttribute name="Location"> <AttributeValue>OH</AttributeValue> </StoreAttribute> </RetailLocation></RetailLocations>
Note:
In batch processing, AddLocation, UpdateLocation, and RemoveLocation actions can be included in the same file as long as each action is in a separate <RetailLocation> section and the actions are not on the same location.
Batch Processing Errors
The following table contains a list of errors that may occur and possible causes.
| Error | Cause |
|---|---|
|
ILLEGAL_RETAIL_TRANSACTION_ID |
The retail location data specified does not match the organization's configured parameters. |
|
INVALID_ATTRIBUTE_VALUE |
Invalid data based on attribute type. For example, characters included in a value for a numeric attribute. |
|
INVALID_DATE_FORMAT |
The data in a date field is not valid date information. |
|
INVALID_EMAIL_ADDRESS |
The retail transaction data specified does not match the organization's configured parameters. |
|
MULTIPLE_VALUES_ON_UNIQUE_ATTRIBUTE_TYPE |
Email address is incorrectly formatted. |
|
RETAIL_LOCATION_ID_INVALID |
The request includes multiple values for an attribute defined as unique. |
|
RETAIL_LOCATION_ID_UNSPECIFIED |
No Location ID specified. |
|
UNKNOWN_ATTRIBUTE_TYPE |
Attribute type not found. |
|
VALUE_NOT_IN_ENUMERATED_ATTRIBUTE_TYPE_VALUES |
The value entered for an attribute is not among the possible enumerated values. |
Batch File Response
Success
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Rejected
Each <RetailLocation> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
If there are any failures, the Batch Import Review pages can be used to determine the reason for the failure (see Batch Import Review).
Remove Retail Location
The purpose of this action is to delete a retail location in the database. The retail location is not actually removed from the database, the record is just marked as inactive (ActiveFlag = False/0). However, if a customer’s business address is the same as the home address, and it was created as a retail location in Customer Engagement, it can be deleted through the Remove Retail Location request.A location attribute name with a blank value will remove the attribute from the location.
Requirements/Restrictions
The minimum data element/attribute that must be included to make a valid request is the RetailLocationID.
Fields
The table below indicates the elements/attributes that may be used in a Remove Retail Location request. The sample request shows the placement of these elements/attributes.
| XML Tag | Comments |
|---|---|
|
<RetailLocation FranchiseLocationFlag=" " |
FranchiseLocationFlag: True or False. Indicates whether the retail location is a franchise. |
|
Action="RemoveLocation"> <RetailLocationID> |
(required) Location ID. Can be 1-12 characters, depending upon the length defined by the organization’s configuration. See the Customer Engagement Implementation Guide for more information. |
Example
A RemoveLocation request should appear similar to the example below. The location data included will vary according to each particular request.
If more than one location is being removed, there should be multiple <RetailLocation> blocks in the batch file.
<?xml version="1.0" encoding="UTF-8"?><RetailLocations> <RetailLocation FranchiseLocationFlag="False" Action="RemoveLocation"> <RetailLocationID><LOCATION_ID></RetailLocationID> </RetailLocation></RetailLocations>
Note:
AddLocation, UpdateLocation, and RemoveLocation actions can be included in the same file as long as each action is in a separate <RetailLocation> section and the actions are not on the same location.
Batch Processing Error
Success
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Rejected
Each <RetailLocation> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
If there are any failures, the Batch Import Review pages can be used to determine the reason for the failure (see Batch Import Review).