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¶
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:
|
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 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¶
{
"schema": {
"unique": [
["product_sku"]
],
"type": "object"
},
"clientCategoryId": "CategoryId",
"imageUrl": null,
"imageData": null,
"itemConfig": {
"level": [{
"level": [{
"levelType": 2,
"qty": 10,
"label": "SubPack",
"level": [{
"levelType": 3,
"qty": 80,
"label": "Item",
"type": "virtual"
}],
"type": "marked",
"attributes": {
"PkgUOM": "SubPack",
"orientation_preference": true,
"DimensionUOM": "CM",
"WeightUOM": "KG",
"length": 10,
"width": 10,
"weight": 16,
"height": 10
},
"barcode": [{
"barcode": "SubPack2"
}]
}],
"levelType": 1,
"attributes": {
"PkgUOM": "Case",
"orientation_preference": true,
"DimensionUOM": "CM",
"WeightUOM": "KG",
"length": 100,
"width": 100,
"weight": 196,
"height": 100
},
"label": "Case",
"type": "marked",
"barcode": [{
"barcode": "Case2"
}],
"qty": 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.
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:
|
||||||||||
qty
required 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. |
||||||||||
barcode
optional 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: {
"barcode": [
{
"barcode": "case1_barcode"
}
]
}
|
||||||||||
attributes
required dict
|
This is an object containing some metadata that is required, like weight and dimensions. Todo Verify the structure and required fields
|
||||||||||
level
optional list
|
This is an optional list of child level objects to this level. |
Item Config Object JSON¶
{
"level": [{
"levelType": 1,
"attributes": {
"PkgUOM": "Case",
"orientation_preference": true,
"DimensionUOM": "CM",
"WeightUOM": "KG",
"length": 100,
"width": 100,
"weight": 196,
"height": 100
},
"label": "Case",
"type": "marked",
"barcode": [{
"barcode": "Case2"
}],
"qty": 1,
"level": [{
"levelType": 2,
"qty": 10,
"label": "SubPack",
"level": [{
"levelType": 3,
"qty": 80,
"label": "Item",
"type": "virtual"
}],
"type": "marked",
"attributes": {
"PkgUOM": "SubPack",
"orientation_preference": true,
"DimensionUOM": "CM",
"WeightUOM": "KG",
"length": 10,
"width": 10,
"weight": 16,
"height": 10
},
"barcode": [{
"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, "qty": 10, "label": "SubPack", "level": [{ "levelType": 3, "qty": 80, "label": "Item", "type": "virtual" }], "type": "marked", "attributes": { "PkgUOM": "SubPack", "orientation_preference": true, "DimensionUOM": "CM", "WeightUOM": "KG", "length": 10, "width": 10, "weight": 16, "height": 10 }, "barcode": [{ "barcode": "SubPack2" }] }], "levelType": 1, "attributes": { "PkgUOM": "Case", "orientation_preference": true, "DimensionUOM": "CM", "WeightUOM": "KG", "length": 100, "width": 100, "weight": 196, "height": 100 }, "label": "Case", "type": "marked", "barcode": [{ "barcode": "Case2" }], "qty": 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, "qty": 10, "label": "SubPack", "level": [{ "levelType": 3, "qty": 80, "label": "Item", "type": "virtual" }], "type": "marked", "attributes": { "PkgUOM": "SubPack", "orientation_preference": true, "DimensionUOM": "CM", "WeightUOM": "KG", "length": 10, "width": 10, "weight": 16, "height": 10 }, "barcode": [{ "barcode": "SubPack2" }] }], "levelType": 1, "attributes": { "PkgUOM": "Case", "orientation_preference": true, "DimensionUOM": "CM", "WeightUOM": "KG", "length": 100, "width": 100, "weight": 196, "height": 100 }, "label": "Case", "type": "marked", "barcode": [{ "barcode": "Case2" }], "qty": 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.