7 Merchandise Hierarchy
This chapter contains the following sections:
Overview
This section provides developers with formats for merchandise hierarchy maintenance requests sent to the Customer Engagement server. The following types of requests are supported:
Hierarchy Structure
Note:
In order to perform Loyalty processing, there must be at least one hierarchy level.
A hierarchy structure is a hierarchical ordered, multi-level system that can be represented by an inverted tree. This structure is dynamic and open-ended. It starts with a single parent node at the top level. One or more child nodes can be connected a single parent node. Each child node can also be a parent and have one or more child nodes.
The following image shows a sample hierarchy structure with the levels identified.
Figure 7-1 Merchandise Hierarchy Structure
Note:
A node (child) can only have one parent. If you try to set up the hierarchy so that a node has more than one parent, only the first parent is recognized and the rest are ignored.
The following information can be set for each node:
-
Merchandise Hierarchy ID
-
Merchandise Hierarchy Level
-
Display Name
-
Description
-
Sort Order
-
Parent Hierarchy ID
-
Parent Hierarchy Level
The Merchandise Hierarchy ID and Merchandise Hierarchy Level are required information and, once set, cannot be changed.
Only the top-most node will not have any Parent Hierarchy references
Add Merchandise Hierarchy
The purpose of this action is to add a level to a merchandise hierarchy.
Requirements/Restrictions
The minimum data elements/attributes that must be included to make a valid request are the MerchandiseHierarchyID and MerchandiseHierarchyLevel.
Fields
The elements in the table below are the elements/attributes that may be used in an AddMerchandiseHierarchy 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 |
|---|---|
|
<MerchandiseHierarchy Action="AddMerchandiseHierarchy"> |
|
|
<MerchandiseHierarchyID> |
(required) User-defined ID for the hierarchy level. |
|
<MerchandiseHierarchyLevel> |
(required) Name for level of hierarchy (must be a configured Merchandise Hierarchy Level Code). |
|
<DisplayName> |
Name for the hierarchy level that is displayed. |
|
<Description> |
Description of the hierarchy level. |
|
<SortOrder> |
Sort order for the hierarchy level. |
|
<ParentHierarchyID> |
Hierarchy ID for the parent node (if any). |
|
<ParentHierarchyLevel> |
Hierarchy Level for the parent node (if any). |
Example
An AddMerchandiseHierarchy request should appear similar to the example below. The merchandise hierarchy data included will vary according to each particular request.
Note:
A node (child) can only have one parent. If you try to set up the hierarchy so that a node has more than one parent, only the first parent is recognized and the rest are ignored.
If more than one hierarchy level or node is included in a batch file, multiple <MerchandiseHierarchy> sections should be used.
<?xml version="1.0" encoding="UTF-8"?><MerchandiseHierarchyMaintenance> <MerchandiseHierarchy Action="AddMerchandiseHierarchy"> <MerchandiseHierarchyID>100-C</MerchandiseHierarchyID> <MerchandiseHierarchyLevel>SUB_DEPT</MerchandiseHierarchyLevel> <DisplayName>Childrens Clothing</DisplayName> <Description>Childrens Clothing</Description> <SortOrder>1</SortOrder> <ParentHierarchyID>100</ParentHierarchyID> <ParentHierarchyLevel>DEPT</ParentHierarchyLevel> </MerchandiseHierarchy></MerchandiseHierarchyMaintenance>
Batch Processing Errors
The following table contains a list of errors that may occur and possible causes:
| Error | Cause |
|---|---|
|
GENERAL_ERROR |
A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant. |
|
MERCHANDISE_HIERARCHY_LEVEL_ID_UNSPECIFIED |
Merchandise Hierarchy Level ID missing in request. |
|
MERCHANDISE_HIERARCHY_LEVEL_UNSPECIFIED |
Merchandise Hierarchy Level missing in request. |
|
MERCHANDISE_LEVEL_NOT_FOUND |
Merchandise level in request is not present in configuration. |
Batch File Response
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Each <MerchandiseHierarchy> 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.
You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).
Results
It is important to remember that the merchandise hierarchy structure is a conceptual structure. The Customer Engagement application does not and cannot enforce the structure rules the user has set up. It is entirely up to the user to enforce these rules. In the example below, the structure rules are configured as DEPT, SUB_DEPT, CLASS, SUB_CLASS, and STYLE_ID. Because the names of these structure rules are configurable, your system may have different names.
The following image shows a partial sample hierarchy structure for a clothing department. The shaded node is the one that was added in the sample request.
Figure 7-2 Sample Hierarchy Structure
Note:
There is nothing to prevent the user from attaching a STYLE_ID node to a DEPT node other than his/her adherence to the established structure rules.
Update Merchandise Hierarchy
The purpose of this action is to create a request to update a level in a merchandise hierarchy with new information or change the parent of the node.
Note:
The Customer Engagement Server does not check logic or verify the structure rules on any update information. For example; if an update request changes the <ParentHierarchyID>, the server does not ensure that the ID actually exists.
Requirements/Restrictions
The minimum data elements/attributes that must be included to make a valid update request are the MerchandiseHierarchyID and MerchandiseHierarchyLevel.
Fields
The elements in the table below are the elements/attributes that may be used in an UpdateMerchandiseHierarchy 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 |
|---|---|
|
<MerchandiseHierarchy Action="UpdateMerchandiseHierarchy"> |
Action is what you are doing to the merchandise hierarchy. |
|
<MerchandiseHierarchyID> |
(required) User-defined ID for the hierarchy level. |
|
<MerchandiseHierarchyLevel> |
(required) Name for level of hierarchy (must be a configured Merchandise Hierarchy Level Code). |
|
<DisplayName> |
Name for the hierarchy level that is displayed. |
|
<Description> |
Description of the hierarchy level. |
|
<ParentHierarchyID> |
Hierarchy ID for the parent node (if any). |
|
<ParentHierarchyLevel> |
Hierarchy Level for the parent node (if any). |
Example
An UpdateMerchandiseHierarchy request should appear similar to the example below. The merchandise hierarchy data included will vary according to each particular request.
Note:
A node (child) can only have one parent. If you attempt to give a node more than one parent, only the first parent is recognized and the rest are ignored.
If more than one hierarchy level or node per level is being updated, there must be multiple <MerchandiseHierarchy> sections.
<?xml version="1.0" encoding="UTF-8"?><MerchandiseHierarchyMaintenance> <MerchandiseHierarchy Action="UpdateMerchandiseHierarchy"> <MerchandiseHierarchyID>100-C</MerchandiseHierarchyID> <MerchandiseHierarchyLevel>SUB_DEPT</MerchandiseHierarchyLevel> <DisplayName>Kids Clothing</DisplayName> <Description>Kids School Clothes</Description> <ParentHierarchyID>100</ParentHierarchyID> <ParentHierarchyLevel>DEPT</ParentHierarchyLevel> </MerchandiseHierarchy></MerchandiseHierarchyMaintenance>
Batch Processing Errors
The following table contains a list of errors that may occur and possible causes:
| Error | Cause |
|---|---|
|
GENERAL_ERROR |
A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant. |
|
MERCHANDISE_HIERARCHY_LEVEL_ID_UNSPECIFIED |
Merchandise Hierarchy Level ID missing in request. |
|
MERCHANDISE_HIERARCHY_LEVEL_UNSPECIFIED |
Merchandise Hierarchy Level missing in request. |
|
MERCHANDISE_LEVEL_NOT_FOUND |
Merchandise level in request is not present in configuration. |
Batch File Response
A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.
Each <MerchandiseHierarchy> 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.
You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).
Results
The following image shows the hierarchy structure after the update request has been processed. The gray node is the node that was affected by the update request.
Figure 7-3 Sample Hierarchy - Update
In this update, we changed the display name of SUB_DEPT 100-C from Childrens Clothing to Kids Clothing and the description from Childrens Clothing to Childrens School Clothes.