Product Management¶
A product in butler system is the final entity uniquely identified by schema of it’s category or an overridden schema at the product level.
Products can be created without creating a parent category or catalog, however it is advised otherwise.
Item Object¶
-
item¶ -
schema¶ optional dict
A Schema Object that defines the schema that this product will follow. If not given, it will inherit the schema of it’s category.
Schema must be given either at category or product level.
-
clientCategoryId¶ optional string (255)
A string id of the category to which this product belongs.
-
attributes¶ required dict
This is an object containing some product metadata that are required, like weight and dimensions. It’s required structure is:
{ "attributes": { "weight": { "uom": { "unit": "KG" }, "value": 1 }, "dimension": { "uom": { "unit": "CM" }, "length": 24, "width": 1, "height": 7 } } }
UOM’s unit can take the following values:
- MM - Millimeter
- CM - Centimeter
- M - Meter
- INCH - Inches
- GM - Gram
- KG - Kilogram
- LBS - Pounds
- POUND - Pounds
- OUNCE - Ounces
-
productAttributes¶ required dict
This is an object containing key-values pairs that describe the product and the system’s behavior for the product. The attribute’s data type and (optionally) display string in different locales should be defined at the catalog level.
The only required attribute inside this is
product_sku.Also, all groups of attributes defined as “unique” in the product’s schema (or inheited schema) must be unique.
Please check Product Feature Attributes for a list of attributes that affect product handling and other features in the system.
-
barcodeList¶ required list
This is a list of barcode objects that uniquely identify this product. Each barcode in the barcode objects in this list must be globally unique for the whole system.
It’s structure should be like this:
{ "barcodeList": [ { "barcode": "Item1Barcode" } ] }
-
description¶ optional string(255)
An optional string describing the product.
-
imageUrl¶ optional string (255)
Should be an accessible link to an image representing the product.
-
itemConfig¶ optional dict
An Item Config Object that defines the storage levels’ configuration of the product.
-
Item Object Sample JSON¶
Changed in version 3.3-s60: itemConfig’s attributes, quantity, and barcodeList changed
{
"schema": {
"unique": [
["product_sku"]
],
"type": "object"
},
"clientCategoryId": "CategoryId",
"imageUrl": null,
"imageData": null,
"itemConfig": {
"level": [{
"level": [{
"levelType": 2,
"quantity": 10,
"label": "SubPack",
"level": [{
"levelType": 3,
"quantity": 80,
"label": "Item",
"type": "virtual"
}],
"type": "marked",
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 16
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 10,
"width": 10,
"height": 10
}
},
"barcodeList": [{
"barcode": "SubPack2"
}]
}],
"levelType": 1,
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 196
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 100,
"width": 100,
"height": 100
}
},
"label": "Case",
"type": "marked",
"barcodeList": [{
"barcode": "Case2"
}],
"quantity": 1
}]
},
"productAttributes": {
"product_sku": "Item1",
"stackable_count": 2,
"fragile": true,
"orientation_preference": true,
"nestable_count": 2,
"nestable_direction": "l",
"nesting_increment": 1.1,
"storage_strategy": "hanger",
"butler_eligible": true,
"scan_required": false
},
"barcodeList": [{
"barcode": "Item1Barcode"
}],
"description": "product description text",
"attributes": {
"weight": {
"uom": {
"unit": "KG"
},
"value": 1
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 24,
"width": 1,
"height": 7
}
}
}
Item Config Object¶
This object can be used to describe the storage levels for a product. For example, if a product comes in a case of 10 eaches, then this metadata can be stored in the product configuration so that the box dimensions, weight, and other attributes don’t have to be passed in each request.
Item config is defined as a recursive object. Each level defines the type, barcode, quantity, and other attributes for that level.
-
itemConfig¶ -
levelType¶ autogenerated integer
This is a unique id for this level
-
label¶ required string
Name of this storage level, like
case,pallet,sub-pack, etc.
-
type¶ required string
This is a string indicating the type of this level. Possible values:
marked: Container with a barcodeunmarked: Container without a barcodevirtual: Not a container (i.e, an each)
-
quantity¶ Changed in version 3.3-s60: Renamed from
qtytoquantityrequired integer
This denotes the quantity of objects in this level that is present in it’s parent level. For root levels, this value must be 1.
For example, for the configuration: “10 eaches in case”, the quantity at case level would be 1, and at each level would be 10.
-
barcodeList¶ Changed in version 3.3-s60: Renamed from
barcodetobarcodeListoptional list
This is a list of barcode objects that uniquely identify this level. Each barcode in the barcode objects in this list must be globally unique for the whole system.
It’s structure should be like this:
{ "barcodeList": [ { "barcode": "case1_barcode" } ] }
-
level¶ optional list
This is an optional list of child level objects to this level.
-
attributes¶ Changed in version 3.3-s60: Structure has been changed to match
item.attributes’s structurerequired dict
This is an object containing some metadata that is required, like weight and dimensions. It’s required structure is:
{ "attributes": { "weight": { "uom": { "unit": "KG" }, "value": 1 }, "dimension": { "uom": { "unit": "CM" }, "length": 24, "width": 1, "height": 7 } } }
Note
In case of eaches, these values are ignored, and those specified in
item.attributesare used.-
weight¶ Changed in version 3.3-s60: Type has been changed from integer to dictionary. See above for example.
Note
For versions 3.3-s58 and before
required integer
Weight of the level in the unit specified by
itemConfig.attributes.WeightUOM.In case of containers (non-each levels), this should be the weight of the container box itself, excluding the weight of items inside it.
In case of eaches, this value is ignored and the weight value is taken from the Item Object.
-
dimension¶ New in version 3.3-s60: See above for example.
-
length, width, height¶ Deprecated since version 3.3-s60: Use
itemConfig.attributes.dimensioninsteadrequired integers
Dimensions of the level in the unit specified by
itemConfig.attributes.DimensionUOM.In case of eaches, this value is ignored and the dimensions are taken from the Item Object.
-
DimensionUOM¶ Deprecated since version 3.3-s60: Use
itemConfig.attributes.dimensioninsteadrequired string
UOM for the dimensions.
- MM - Millimeter
- CM - Centimeter
- M - Meter
- INCH - Inches
-
WeightUOM¶ Deprecated since version 3.3-s60: Use
itemConfig.attributes.weightinsteadrequired string
UOM for the weight.
- GM - Gram
- KG - Kilogram
- LBS - Pounds
- POUND - Pounds
- OUNCE - Ounces
-
-
Item Config Object JSON¶
Changed in version 3.3-s60: attributes, quantity, and barcodeList changed
{
"level": [{
"levelType": 1,
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 196
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 100,
"width": 100,
"height": 100
}
},
"label": "Case",
"type": "marked",
"barcodeList": [{
"barcode": "Case2"
}],
"quantity": 1,
"level": [{
"levelType": 2,
"quantity": 10,
"label": "SubPack",
"level": [{
"levelType": 3,
"quantity": 80,
"label": "Item",
"type": "virtual"
}],
"type": "marked",
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 16
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 10,
"width": 10,
"height": 10
}
},
"barcodeList": [{
"barcode": "SubPack2"
}]
}]
}]
}
Product Feature Attributes¶
Create or Update Items¶
-
POST/api-gateway/mdm-service/wms-masterdata/item¶ To create or update a product, an Item Object has to be sent in a HTTP POST request to the above endpoint. The newly created or modified object will be returned in the response if the request is successful.
Request Headers: - Content-Type – the request’s content-type has to be passed in this header
- Accept – the response content type depends on Accept header
- Authorization – OAuth token to authenticate
Status Codes: - 200 OK – No error
- 400 Bad Request – Bad data
Example request:POST /api-gateway/mdm-service/wms-masterdata/item HTTP/1.1 Host: example.com Content-Type: application/json Accept: application/json, text/javascript
{ "schema": { "unique": [ ["product_sku"] ], "type": "object" }, "clientCategoryId": "CategoryId", "imageUrl": null, "imageData": null, "itemConfig": { "level": [{ "level": [{ "levelType": 2, "quantity": 10, "label": "SubPack", "level": [{ "levelType": 3, "quantity": 80, "label": "Item", "type": "virtual" }], "type": "marked", "attributes": { "orientation_preference": true, "weight": { "uom": { "unit": "KG" }, "value": 16 }, "dimension": { "uom": { "unit": "CM" }, "length": 10, "width": 10, "height": 10 } }, "barcodeList": [{ "barcode": "SubPack2" }] }], "levelType": 1, "attributes": { "orientation_preference": true, "weight": { "uom": { "unit": "KG" }, "value": 196 }, "dimension": { "uom": { "unit": "CM" }, "length": 100, "width": 100, "height": 100 } }, "label": "Case", "type": "marked", "barcodeList": [{ "barcode": "Case2" }], "quantity": 1 }] }, "productAttributes": { "product_sku": "Item1", "stackable_count": 2, "fragile": true, "orientation_preference": true, "nestable_count": 2, "nestable_direction": "l", "nesting_increment": 1.1, "storage_strategy": "hanger", "butler_eligible": true, "scan_required": false }, "barcodeList": [{ "barcode": "Item1Barcode" }], "description": "product description text", "attributes": { "weight": { "uom": { "unit": "KG" }, "value": 1 }, "dimension": { "uom": { "unit": "CM" }, "length": 24, "width": 1, "height": 7 } } }
Example Response:HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8
{ "schema": { "unique": [ ["product_sku"] ], "type": "object" }, "clientCategoryId": "CategoryId", "imageUrl": null, "imageData": null, "itemConfig": { "level": [{ "level": [{ "levelType": 2, "quantity": 10, "label": "SubPack", "level": [{ "levelType": 3, "quantity": 80, "label": "Item", "type": "virtual" }], "type": "marked", "attributes": { "orientation_preference": true, "weight": { "uom": { "unit": "KG" }, "value": 16 }, "dimension": { "uom": { "unit": "CM" }, "length": 10, "width": 10, "height": 10 } }, "barcodeList": [{ "barcode": "SubPack2" }] }], "levelType": 1, "attributes": { "orientation_preference": true, "weight": { "uom": { "unit": "KG" }, "value": 196 }, "dimension": { "uom": { "unit": "CM" }, "length": 100, "width": 100, "height": 100 } }, "label": "Case", "type": "marked", "barcodeList": [{ "barcode": "Case2" }], "quantity": 1 }] }, "productAttributes": { "product_sku": "Item1", "stackable_count": 2, "fragile": true, "orientation_preference": true, "nestable_count": 2, "nestable_direction": "l", "nesting_increment": 1.1, "storage_strategy": "hanger", "butler_eligible": true, "scan_required": false }, "barcodeList": [{ "barcode": "Item1Barcode" }], "description": "product description text", "attributes": { "weight": { "uom": { "unit": "KG" }, "value": 1 }, "dimension": { "uom": { "unit": "CM" }, "length": 24, "width": 1, "height": 7 } } }
Search for an Item¶
Products in the system can be searched using their unique attributes.
-
POST/api-gateway/mdm-service/wms-masterdata/item/search_v2¶ For searching, a list of filter objects are given, and the response is a list of Item Objects matching the given filters.
Request Headers: - Content-Type – the request’s content-type has to be passed in this header
- Accept – the response content type depends on Accept header
- Authorization – OAuth token to authenticate
Request JSON Object: - filter_params –
This is a list of search filter objects that have to be applied when searching.
Each filter object has three attributes:
key: The attribute key on which to apply the filter. The key must be one of the unique attributes defined in the item’s schema.operator: The filter operator. Supported operators:=.value: The value against which the attribute key is matched.
Status Codes: - 200 OK – No error
- 400 Bad Request – Bad data
Example Request:POST /api-gateway/mdm-service/wms-masterdata/item/search_v2 HTTP/1.1 Host: example.com Content-Type: application/json Accept: application/json, text/javascript { "filter_params": [{ "key": "product_sku", "operator": "=", "value": "1911" }] }
Example Response:HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8
[ { "id": 7, "clientItemId": null, "uom": null, "description": "product description text", "clientCategoryId": null, "barcodeList": [ { "id": 7, "barcode": "1911" } ], "serialised": false, "imageUrl": null, "schema": { "unique": [ [ "product_sku" ] ], "type": "object" }, "productAttributes": { "product_sku": "1911", "exclusion_tags": { "face": [], "slot": [], "msu": [], "shelf": [] } }, "displayKeyList": [], "attributes": { "id": 7, "dimension": { "length": 24.0, "width": 1.0, "height": 7.0, "uom": { "id": 2, "type": "DIMENSION", "unit": "CM", "conversionFactor": 1.0 } }, "volume": null, "weight": { "value": 1.0, "uom": { "id": 1, "type": "WEIGHT", "unit": "KG", "conversionFactor": 1.0 } }, "status": null }, "imageData": null, "itemConfig": null, "jsonProductAttributes": { "product_sku": "1911", "exclusion_tags": { "face": [], "slot": [], "msu": [], "shelf": [] } }, "jsonSchema": { "unique": [ [ "product_sku" ] ], "type": "object" } } ]
Note
If there are no results matching the filter, the response is an empty list
[]with HTTP code 200.
Item Created Notification¶
New in version 4.2.0.
This notification is generated whenever an item is successfully created in the system.
{
"notification_type": "item-create",
"version_number": "1.5.0",
"notification_id": "unique_id_of_this_notification",
"notification_data": {
"schema": {
"unique": [
["product_sku"]
],
"type": "object"
},
"clientCategoryId": "CategoryId",
"imageUrl": null,
"imageData": null,
"itemConfig": {
"level": [{
"level": [{
"levelType": 2,
"quantity": 10,
"label": "SubPack",
"level": [{
"levelType": 3,
"quantity": 80,
"label": "Item",
"type": "virtual"
}],
"type": "marked",
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 16
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 10,
"width": 10,
"height": 10
}
},
"barcodeList": [{
"barcode": "SubPack2"
}]
}],
"levelType": 1,
"attributes": {
"orientation_preference": true,
"weight": {
"uom": {
"unit": "KG"
},
"value": 196
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 100,
"width": 100,
"height": 100
}
},
"label": "Case",
"type": "marked",
"barcodeList": [{
"barcode": "Case2"
}],
"quantity": 1
}]
},
"productAttributes": {
"product_sku": "Item1",
"stackable_count": 2,
"fragile": true,
"orientation_preference": true,
"nestable_count": 2,
"nestable_direction": "l",
"nesting_increment": 1.1,
"storage_strategy": "hanger",
"butler_eligible": true,
"scan_required": false
},
"barcodeList": [{
"barcode": "Item1Barcode"
}],
"description": "product description text",
"attributes": {
"weight": {
"uom": {
"unit": "KG"
},
"value": 1
},
"dimension": {
"uom": {
"unit": "CM"
},
"length": 24,
"width": 1,
"height": 7
}
}
}
}