Warning: This document is for an old version of Grey Matter. The latest version is v10.1.0.

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

{
    "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.

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 barcode
  • unmarked: Container without a barcode
  • virtual: Not a container (i.e, an each)
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

weight

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.

length, width, height

required 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

required string

UOM for the dimensions.

  • MM - Millimeter
  • CM - Centimeter
  • M - Meter
  • INCH - Inches
WeightUOM

required string

UOM for the weight.

  • GM - Gram
  • KG - Kilogram
  • LBS - Pounds
  • POUND - Pounds
  • OUNCE - Ounces
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

Todo

Write about some product attributes affecting features

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:
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:
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.