PUZZLE REST interface (3.1.1)

• Attribute heightOverhang in LoadingDevices is not yet supported. A client can set a value and it is stored in the internal representation of a job, but PUZZLE does not evaluate this attribute during optimization.

• URL version tags remain v1 even for REST API version 2. Endpoint URLs are unchanged. You can retrieve the installed version of the REST API through the /info endpoint.

Component	Category	Description	Date
PUZZLE REST API 3.1.1	Changed	PUZZLE core version 53.1.0.
	Added	Provided documentation for load sequencing parameters Sequencing.CreateSequence and Sequencing.AccessOptions.	2022-03-07
	Added	Provided documentation for the new TRAY_PALLET and US_42X48_PAL loading device types.	2022-01-07
	Added	Documentation for the new cost and maxDropHeight properties of loading devices.	2022-01-07
	Fixed	Fixed typos in this document.	2021-12-22
	Added	Introduced new Parameters Packing.SubSetQuantity and Packing.BuildLinkedSets.	2021-12-15
	Added	Documentation for Sets comprising multiple order items.	2021-12-15
	Added	New optional attribute OrderLine#loadingPriority.
PUZZLE Reporter Plugin	New Plugin	First release of the reporter plugin is available. The reporter plugin allows a client to request PUZZLE to compute a report for a solution.
PUZZLE REST API 2.3.0	Dependency	PUZZLE core version 53.1.0.
	Dependency	PUZZLE REST container version 5.0.0
	Fixed	Fix error in documentation: Values provided in the attribute Solution#Position#orientation ranges from 1 to 12, not 0 to 11. Update resolution table.
	Fixed	PUZZLE will return only those parameters, that have been provided by the client.
	Fixed	The validation will now fail if maxLoadWeight is set to 0.
	Fixed	JSON objects that contain multiple attributes having the same name are no longer accepted.
	Documentation	Added description of the item orientation in positions of a solution.
	Documentation	Add missing value range annotations in the structure of the response of POST /jobs.
	Documentation	Add and fix description of the attributes orientation and immutable of a position of a solution in the response of GET /jobs/{jobId}.
	Documentation	Added default units to data object documentation.
	Improvement	PUZZLE now logs any received HTTP request body, if the log level is set to debug.
	Documentation	Document parameter Search.ExpirationTime.
PUZZLE REST API 2.1.0	Changed	Suppressing most of the returned and undocumented parameters in the returned JSON representation of a job.
	Dependency	PUZZLE core version 48.0.0.
	Dependency	PUZZLE REST container version 4.1.0
PUZZLE REST API 2.0.0	Improvement	Rename attributes in representation of solutions: renamed attributes loadingDevice to loadingDeviceNumber and orderLine to orderLineNumber. [Breaking Change]
	Fixed	In case of an error during computation, the state of the job will be set to DONE. An error message will be added to the metadata of the job.
	Improvement	Add new endpoint to provide the memory usage of this PUZZLE instance. PUZZLE provides the used memory, the free memory and the maximum possible used heap memory as well as the number of jobs stored by this PUZZLE instance.
	Improvement	Add new attributes to metadata, to provide the messages of errors that occurred while PUZZLE computes solutions.
	Bug	The summaries for a job has returned an error, if PUZZLE has created a solution with loadingDeviceNumber set to null. For such a solution, PUZZLE now sets the loadingDeviceNumber to the empty string and does not return an error.
	Improvement	The picklists now contains the attribute loadingDeviceNumber which contains the loadingDeviceNumber of the used solution.
PUZZLE REST API 1.0.0-beta	Improvement	Semantic and representation of loading devices has changed: length, width and height of a loading device always describe the available load space, NOT the dimensions of the loading device itself. [Breaking Change]
	Improvement	The type of the loading device is now determined from the attribute type only, not from the combination of the attributes type and loadingDeviceType. Attribute type now contains the specific type of the loading device (in previous version, the attribute loadingDeviceType has contained the specific type). [Breaking Change]
	Improvement	Client can specify a carton by outer dimensions. If both, (inner) dimensions and outer dimensions are given, the (inner) dimensions always overrides the outer dimensions. For the conversion of inner and outer dimensions, a client must have set the attribute materialThickness. The client must therefore always specify the attribute materialThickness for a box.
	Improvement	Attribute carrierHeight represents the height of the pallet itself.
	Improvement	Attributes lengthOverhang and widthOverhang are optional attributes. If not provided by a client, PUZZLE initializes them with 0.
	Improvement	Client can provide more than one loading device in a job. PUZZLE considers only the first loading device, all further loading devices are ignored yet.
	Improvement	The client can now also request the validation of a job in state VALID.
	Improvement	The Metadata contains the duration until expiration of the job in seconds in the attribute timeIntervalUntilExpiration.
	Improvement	Summaries contains the number of the loading device used for a solution in the attribute loadingDeviceNumber.
	Improvement	PUZZLE now always returns error messages as JSON objects with the attributes errorMessage, errorClass and additionalInformation.
	Improvement	PUZZLE response with information about the running PUZZLE instance for a GET request to /info
	Improvement	PUZZLE can send CORS header. This feature must be activated by setting Rest.useCorsHeader=true in the configuration file puzzle.parameter. PUZZLE reads the value of the Access-Control-Allow-Origin HTTP header from the parameter Rest.allowOrigin from the same file.
	Change	PUZZLE returns HTTP status code 400 instead of 422 in case of a JSON parsing errors.
	Change	Attribute maximumLoadWeight renamed to maxLoadWeight. This is a Breaking Change.
	Bug	If attribute type of a loading device has value box, PUZZLE has returned an error.
	Bug	POST /jobs returns a JSON object with attribute jobId instead of directly returning the value of jobId.
	Change	Support for container loading is postponed, hence loading device types "TWENTY_FEET" , "FOURTY_FEET","FOURTY_FIVE_HC", "FOURTY_FIVE_PW" and "FIFTY_THREE_HC" are removed.
	Dependency	PUZZLE core version 47.0.0.
	Dependency	PUZZLE REST container version 4.0.4.
	Documentation	Added two examples for jobs, one for a job using a pallet, one for a job using a carton.
	Documentation	New structure of documentation. Description of HTTP Endpoints consolidated in section HTTP Requests and new sections describing the data objects, the interaction with PUZZLE, the error handling and release notes are added. General description renamed to Introduction
	Documentation	Description of plugins is structured in a table
	Documentation	Figures of state machines are updated
	Documentation	Description of parameters is added
	Documentation	Description of HTTP Requests now contains response samples for HTTP status codes 400, 404 and 500 and a description of preconditions
	Documentation	Description of extension keys is added
	Documentation	pallet shows how to add a customerId` to a job
	Documentation	Keys and values of parameters must always be strings. This concerns the endpoints POST /jobs and PUT /jobs/{jobId}
	Documentation	Example for POST /jobs/{jobId}/validation with HTTP status code 200 is fixed and example for carton example is added

The PUZZLE REST interface offers an API for the PUZZLE optimization program in form of HTTP Requests. PUZZLE performs a 3D load optimization for packing or palletization tasks or jobs. A client describes a task by providing and posting a JSON representation of a job. After data validation and upon request, PUZZLE computes solutions from the given order, the available loading devices and the parameters within the job. Computed solutions include the chosen loading device and a series of positions referring to orderlines of the given order. After computation, a client can retrieve solutions in multiple representations and level of detail:

• a detailed JSON representation including coordinates for all positions,
• a summary with basic data for every computed unit load or
• a pick list with item quantities for every load.

Plug-Ins are available for additional, graphical representations of solutions.

The following explanations contain a description of the JSON objects that are used to transfer data between a client and PUZZLE.

The data object required for a load optimization is called a job. A job contains any data PUZZLE needs to know to perform computations. A job encloses data of a single order including its order lines and the corresponding item master data, data for loading devices such as cartons or pallets and parameter values used to influence the way PUZZLE optimizes. Once a job is computed by PUZZLE, it will "contain" the results from the optimization. These results are called solutions.

A job contains exactly one order. The order describes a set of physical items and their quantities that PUZZLE shall place in (or upon) loading devices. An order has an orderNumber and contains a set of orderLines with at least one entry.

An order contains one or more orderLines.

Attribute	Value Format	Description	Default	Unit
orderLineNumber	string	Client chosen unique alphanumeric identifier for an item or a SKU.
quantity	integer	The quantity to be stacked.
orderitem		The masterdata describing the item to be stacked.
loadingPriority	integer	Specifies the priority in which PUZZLE considers the order lines. OrderLines that contain the identical value for the 'loadingPriority' attribute are combined into groups that are prioritized equally. PUZZLE considers the "loadingPriority" in ascending order for each order. OrderLines with a value of null for the 'loadingPriority' attribute can be stacked at any time. The 'loadingPriority' attribute in JSON representations of a job is optional. It will always be present if the value of loadingPriority is not null.	null

An order item describes the physical properties of a SKU for PUZZLE. An order item is of cubic shape. A client must provide an identifier, outer dimensions and a gross weight value for it. With default settings, PUZZLE will place items only with their height vertical upon the base of the loading device. In case other orientations are permitted, these permissions must be given from the client side by setting optional attributes explicitly.

Attribute	Value Format	Description	Default	Unit
number	string	Client chosen alphanumeric identifier for an item or a SKU.
name	string	Item name, this is a free text description.
group	string	Optional group identifier of the item. Several items may belong to the same group.
length	integer	Item length.		millimeter
width	integer	Item width.		millimeter
height	integer	Item height.		millimeter
grossWeight	integer	Total weight of the item or SKU including packaging.		gram
maxWeightOnTop	integer	Maximum cumulated weight on top of the item.		gram
lengthVerticalPermitted	boolean	If true, the item may be placed with its length perpendicular to the base of the loading device.	false
widthVerticalPermitted	boolean	If true, the item may be placed with its width perpendicular to the base of the loading device.	false
heightVerticalPermitted	boolean	If true, the item may be placed with its height perpendicular to the base of the loading device.	true

An order may contain the same orderItem data more than once.

In certain cases, products are to be packed which consist of several packages belonging together. Within PUZZLE, such products are called sets. Sets are identified by a specific item number syntax. An OrderItem number in square brackets, and without any other additions, provides the so-called set-header. A set-component is defined by an additional number directly behind the set-header number in brackets. Component numbers must not be empty and must be unique within the set and must not contain square brackets (a set within a set is not supported). An Order may comprise different sets.

Example of a Set

The following example defines a complete set with two components. The set contains a larger component of size 600 x 400 x 300 and a weight of 10000 and a smaller component of size 400 x 300 x 100 and a weight of 3000. A set must have at least one, but may have more than two components.

number	description	length	width	height	weight	...
[340670]	Set-Header
[340670]80010	Set-Component 1	600	400	300	10000	...
[340670]80020	Set-Component 2	400	300	100	3000	...

Quantities for Sets

A set is like a bill of material. Quantities for components specify the amount of packages within a single set. The quantity given in the set-header defines the amount of complete sets within the Order. Within the following example, the first component occurs only once in a single set. The second component is required twice for each set. Thus, the following three OrderLines include a total of 12 (= 4 x (1 + 2)) packages that shall be loaded.

orderLineNumber	orderitem	quantity	...
10	[340670]...	4	...
11	[340670]80010...	1	...
12	[340670]80020...	2	...

Loading Sets with multiple OrderItems

Sets are only stacked completely. It is up to the client to assure, that a LoadingDevice is present within the job, that can hold all components with given quantities for at least a single complete set. Parameters to control set-component stacking are listed and explained in the Parameters section of this specification.

A loading device primarily describes the available space and the permitted maximum load weight for the optimization. PUZZLE supports a variety of loading devices such as different pallet and carton types. Dimensions of any loading device are not fixed and can be initialized with required values. A job may contain one or more loading devices from which PUZZLE can choose. A loading device is the abstraction of a real loading aid and allows a client to describe all permitted cartons or pallets in a similar manner. Loading devices have the following attributes in common:

Attribute	Value Format	Description	Units of Measure
type	string	See below for a detailed explanation and permitted type values
number	string	A unique loading device identifier within a job. PUZZLE will use the given number as a reference in solutions.
name	string	A free text name for the loading device
length	integer	Length of the available load space. For cartons this is the inner length, for a pallet this is the pallet length.	mm
width	integer	Width of the available load space. For cartons this is the inner width, for a pallet this is the pallet width.	mm
height	integer	Height of the available load space. For cartons this is the inner height, for a pallet this is the maximum stacking height on top of the pallet.	mm
lengthOverhang	integer	Optional overhang along the length. A negative value (underhang) defines a reserved space that shall be left empty.	mm
widthOverhang	integer	Optional overhang along the width. A negative value (underhang) defines a reserved space that shall be left empty.	mm
maxLoadWeight	integer	The maximum permitted load weight.	g
emptyWeight	integer	The empty or tare weight of the loading device itself without any load.	g
maxDropHeight	integer	An optional value, that declares the minimum height of the bottom edge of any placed package. For a value of e.g. 0 (zero) only the bottom layer of the loading devices will be filled.	mm
cost	integer	The expenditure arising for use of the loading device. This is an optional value

Loading Device Type

Each loading device must have a particular type value. PUZZLE will use the supplied value to identify if the given loading device is a pallet or carton. The type also specifies the graphics PUZZLE will provide in a HTML, PNG or PDF. Multiple loading devices of a job may have the same type attribute value.

The type value must be one of the following:

Type Value	Description
carton type	carton description
FEFCO0200	FEFCO 0200 slotted type box without lid.
FEFCO0201	FEFCO 0201 regular slotted box.
FEFCO0420	FEFCO 0420 folder type box.
FEFCO0426	FEFCO 0426 folder type box.
FEFCO0427	FEFCO 0427 folder type box.
FEFCO0470	FEFCO 0470 folder type box.
pallet type	pallet description	Default length x width x carrier height in mm
AUS1_PAL	Australian standard pallet.	1165 x 1165 x 160
AUS2_PAL	Australian standard pallet.	940 x 940 x 160
BLOCK_PAL	A simple block pallet	1200 x 800 x 144
CHEP_AUTO_PAL	CHEP-style automotive pallet.	1200 x 1000 x 144
CHEP_48X40_PAL	CHEP-style 48 x 40 inch pallet.	1219 x 1016 x 124
CHEP_48X40_STRINGER_PAL	CHEP-style 48 x 40 inch stringer pallet.	1219 x 1016 x 123
CHEP_48X42_PAL	CHEP-style 48 x 42 inch pallet.	1219 x 1067 x 127
CHEPA_PAL	CHEP-style automotive 4-way half pallet.	1000 x 600 x 144
CP1_PAL	CP 1 pallet for the chemical industry.	1200 x 1000 x 138
CP2_PAL	CP 2 pallet for the chemical industry.	1200 x 800 x 138
CP3_PAL	CP 3 pallet for the chemical industry.	1140 x 1140 x 138
CP4_PAL	CP 4 pallet for the chemical industry.	1300 x 1100 x 138
CP5_PAL	CP 5 pallet for the chemical industry.	1140 x 760 x 138
CP6_PAL	CP 6 pallet for the chemical industry.	1000 x 1200 x 156
CP7_PAL	CP 7 pallet for the chemical industry.	1100 x 1300 x 156
CP8_PAL	CP 8 pallet for the chemical industry.	1140 x 1140 x 156
CP9_PAL	CP 9 pallet for the chemical industry.	1140 x 1140 x 156
CUSTOM_PAL	A custom pallet. It will be drawn like a EURO_PAL.
DUSS1_PAL	EUR 6 euro norm pallet. A small 4-way window pallet.	800 x 600 x 144
DUSS2_PAL	Düsseldorfer pallet.	800 x 600 x 160
DUSS3_PAL	Düsseldorfer half pallet.	600 x 800 x 166
EURO_PAL	EUR 1 euro norm pallet.	1200 x 800 x 144
EURO2_PAL	EUR 2 euro norm (industry) pallet.	1200 x 1000 x 144
TRAY_PALLET	Tray pallet for the storage of packed furniture.	2200 x 1400 x 30
US_42X42_PAL	US 42 x 42 inch pallet.	1067 x 1067 x 139
US_42X48_PAL	US 42 x 48 inch GMA-type pallet with seven deck boards.	1067 x 1219 x 115
US_48X40_D8_PAL	US 48 x 40 inch GMA-type pallet with 8 deck boards.	1219 x 1016 x 152
US_48X40_PAL	US 48 x 40 inch GMA-type pallet with 7 deck boards.	1219 x 1016 x 152
US_48X48_WNG_PAL	US 48 x 48 inch winged pallet.	1219 x 1219 x 133

Cartons

Material Thickness

Any carton has a mandatory materialThickness value. The value specifies the cardboard thickness (or strength) and PUZZLE uses the materialThickness for the conversion between inner and outer dimensions.

Outer Dimensions

Whenever inner dimensions for length, width and height are supplied, PUZZLE will use them together with the type (and the associated cardboard folding) and the given material thickness value to compute the outer dimensions. Specifying a carton using inner dimensions is the recommended way. Nevertheless, a client can specify the outer dimensions outerLength, outerWidth and outerHeight for a carton, omit the inner dimensions and let PUZZLE compute inner dimensions using the given carton type and the material thickness.

Load Underhang

A carton cannot have a load overhang. However, space can be left empty by supplying negative values for overhangLength and or overhangWidth. Such load underhang is always symmetrical and counts individually for each affected side. For example, if a client specifies a length overhang of -10 (mm), PUZZLE does not place any order item closer than 10 mm to the left and 10 mm to the right to the carton sides. The same semantic holds for width overhang. A positive overhang value is not permitted for cartons.

Carton Attribute Interrelations

The following figures display the interrelations between the properties of a carton.

Pallets

Carrier Height

For any pallet, the client must provide a value for the height of the pallet itself. This is the carrierHeight value.

Outer Dimensions

The load space above the pallet cannot be specified using outer dimensions. Given width and length attributes define the width and length of the pallet. The height value defines the maximum permitted stacking height upon the pallet.

Load Overhang

A client can provide optional values for permitted load over- or underhang along the length or the width of the pallet by supplying positive (overhang) or negative (underhang) values for lengthOverhang and or widthOverhang.

Pallet Attribute Interrelations

The following figure displays the interrelations between the properties of a pallet.

Parameters are used to influence the PUZZLE load optimization. Parameters are key-value pairs (both strings) stored in the parameters attribute of the job. PUZZLE uses default values for each parameter. A client can override any default value by explicitly setting a parameter value. Only the following parameters are designed to be set explicitly by a client. Setting undocumented parameters may result in undefined behavior.

PUZZLE returns exactly the parameters that are explicitly set by the customer in the representation of the job data.

Parameter Name	Description	Default Value
Search.SolutionCount	The maximum amount of solutions that PUZZLE shall compute for the job. Note that this is a maximum value and PUZZLE may provide fewer solutions.	1
Search.MaxIterations	Upper limit for the iteration counter of the PUZZLE optimizer.	10000
SpaceModel.WeightDistributionTest	Toggles weight distribution on (true) or off (false). If switched on, PUZZLE will verify that no position will exceed the maxWeightOnTop maximum payload of any OrderItem below. Note that PUZZLE uses an approximation algorithm for weight distribution.	true
SpaceModel.MinimumStability	A percentage value that controls the required stability value for any position of an order item. The higher the value, the more support and overlap with other items is required for a position.	7000
Optimizer.UseProxyItems	If set to true, PUZZLE is permitted an internal grouping of order items with "similar" dimensions and other properties. PUZZLE will resolve this internal grouping before returning solutions. This parameter is not related to the "group" attribute of an order item.	false
Search.ExpirationTime	Limits the number of virtual seconds that PUZZLE can spent on a job for optimization. The duration of a virtual second only roughly corresponds to a real second. PUZZLE uses this virtual unit of time to achieve computation power and platform-independent results. The given value must be a non-negative integer. If this attribute remains 0, PUZZLE is optimizing without a timeout and computation can last very long. Thus, it is very reasonable to explicitly set this parameter to a value greater than zero.	0
Packing.SubSetQuantity	A parameter related to set loading. In set loading, products exist, that consist of several packages that must not be split across different unit loads. The parameter specifies the maximum permitted amount of same sets in a single pass during optimization. For the minimum value of 1, a set - with all its component packages - must be packed completely before starting any next one. This will result in loads, where a complete set can be obtained without the need to repack. For higher values n, PUZZLE is permitted to combine all components of multiple (2...n) same sets in a single pass.	2
Packing.BuildLinkedSets	This parameter permits override of Packing.SubSetQuantity. If set to false, PUZZLE will attempt to pack multiple Sets on its own, trying different quantities and ignoring any value given as Packing.SubSetQuantity. As a result, components of a single set may no longer be linked and kept together, but appear in various areas of the load.	true
	Creating and obtaining a loading sequence
Sequencing.CreateSequence	A boolean flag to toggle the creation of a loading sequence on or off. If set to true, PUZZLE will provide a numeric Sequencing.SequenceNumber entry in the returned extension of any Position of a computed solution indicating the loading sequence that can be used to stack items on a pallet or pack items into a carton. The lowest SequenceNumber returned will be 1. The following graphics illustrates the returned values in the extension of each Position for default Sequencing.AccessOptions.	false
Sequencing.AccessOptions	A concatenated, semicolon delimited string with a combination of any of the following access options that PUZZLE may utilize to create a loading sequence: FRONT_LEFT, FRONT, FRONT_RIGHT, BACK_LEFT, BACK, BACK_RIGHT, LEFT, RIGHT, TOP. In general, various sequences can be formed from the bottom towards the top of the load. Access options provide a way to influence the computation of the loading sequence to better suit the type of application. A given value of e.g. "BACK;FRONT;LEFT" indicates, that there is no access from the right side when packing or loading. Any provided parameter value must not be empty and thus contain at least a single access option. For the default setting, any area that is accessible from the top will be available for stacking a next item. The following graphics depicts a top view on a pallet with all options and the coordinate system.	"TOP"

A solution contains the following data.

Attribute	Value Format	Description
id	integer	A job unique solution identifier generated by PUZZLE.
positions	Object Array	An array of position objects including type, orderline, x, y, z coordinate and item orientation.
remainder	Object Array	An array of remainder orderlines including orderlineNumber and remaining quantity.

For every job, PUZZLE will provide at least one solution. If no order items of a job fit in a loading device, the positions array of the solution is an empty array and the remainder is equal to the order lines provided by the client.

Every solution is a variant to pack item(s) of an order onto a loading device. Different variants may have different sets of packed items, but each solution uses the same loading device.

Item Orientation

The orientation attribute of a position is a bit-coded integer value that encodes:

• which dimension PUZZLE has placed vertical to the pallet or the bottom of the carton
• and the degree of counterclockwise rotation about this vertical dimension

The following table shows the resolution of the possible values of the orientation attribute:

value	Which dimension is vertical to the pallet or the bottom of the carton	Degree of counterclockwise rotation about the vertical dimension
1	height	0
2	height	90
3	height	180
4	height	270
5	width	0
6	width	90
7	width	180
8	width	270
9	length	0
10	length	90
11	length	180
12	length	270

The optional extension provides a flexible way to pass and retrieve additional data to and from PUZZLE. Extensions are key value maps. Keys and values are of type string. The following data objects offer an optional extension:

• order
• orderItem
• each entry in the orderLines
• each entry in loadingDevices
• each solution entry
• each position entry within a solution

PUZZLE itself uses this mechanism to transfer additional data between different components. To prevent extension data overrides, a client should use a client specific prefix to avoid key name conflicts when using extensions. Key "myCompanyName.customerId" with value "myCustomerId" is an example for a client side extension entry in an order.

Extension keys for client usage

The following extension keys are reserved to set color values for order items and loading devices.

Extension Data Object	Key Name	Description	Format	Sample Value
orderItem	Renderer.OrderItem.itemColorFront	Individual item front color.	string with format "#rrggbb"	"#00ff00" for green.
orderItem	Renderer.OrderItem.itemColorSide	Individual item side color.	string with format "#rrggbb"	"#ffff00" for yellow.
orderItem	Renderer.OrderItem.itemColorTop	Individual item top color.	string with format "#rrggbb"	"#0000ff" for blue.
orderItem	Renderer.OrderItem.color	Color value of an item.	string with format "#rrggbb"	"#ff0000" for red.
loadingDevice	Renderer.LoadingDevice.loadingDeviceColor	Color value of a loading device.	string with format "#rrggbb"

The given color values will be recognized by PUZZLE plug-ins when rendering graphics or creating reports. PUZZLE evaluates extensions independently of the aggregation relationships between parts of the job. An extension entry within the order will not be written to the orderLine extension automatically.

The objective of this section is to provide an understanding of the interaction between a client and PUZZLE. Section "HTTP Requests" describes the technical details of the interaction steps.

From the client's point of view, the following state machine shows the basic interaction between a client and PUZZLE.

Create

As first step, a client creates a job by sending a JSON representation of a job to PUZZLE. PUZZLE creates a new job with the data from the JSON and returns a unique ID for the newly created job, referred to as the jobId. The state of every newly created job is CREATED.

A client must provide the jobId in all subsequent steps of interaction with PUZZLE to specify the job.

PUZZLE does not store jobs permanently. Therefore, a client must resend jobs after restarting PUZZLE and PUZZLE can return a different jobId for the same JSON representation.

The successful creation of a job does not include validation of the semantic constraints for the data in the job.

Validate

As a second step, a client requests such a validation of semantic constraints. You can do this by request PUZZLE to validate the job.

PUZZLE then verifies predefined semantic constraints about the data in the job. If the job's data does not violate any of the semantic constraints, PUZZLE changes the state of the job to VALID.

If the data of the job violates constraints, PUZZLE keeps the state of the job on CREATED.

Compute

For a valid job, a client requests PUZZLE to compute solutions for a job. PUZZLE indicates acceptance of the request by changing the state of the job to SUBMITTED.

PUZZLE internally manages a queue of jobs for which it should compute solutions, and processes this queue in an unpredictable order, depending on available resources and licensed number of PUZZLE cores.

Wait for state DONE

After PUZZLE has computed solutions for a job, PUZZLE changes the state of this job to DONE. To detect this change in the state of the job, a client must periodically requests the job's metadata.

Retrieve Solutions

If the state is DONE, a client can retrieve representations of a job's solutions.

PUZZLE creates the representations on a per-request basis. PUZZLE provides overview statistics for all solutions of a job and picklists for all solutions of a job. Further representations are available via plugins.

Three steps are available to the client for additional interaction with PUZZLE: Abort computation, replace a job as a whole and delete a job. The following state chart adds two optional steps to the basic interaction: Abort computation and replace a job as a whole.

Replace a job

A client can replace a job as a whole in any state except SUBMITTED. After replacing a job, the state of the job is always CREATED. You can replace the data of a job to resolve violations of constraints.

Abort computation

A client can revoke the request to compute solutions, by aborting the computation of a job. Then PUZZLE reset the job to state VALID and deletes all computed data for the job.

Delete

Further, a client can explicitly delete a job in any state. If a client deletes a job in the state SUBMITTED, PUZZLE does automatically abort the computation of the job and then continue with the deletion of the job.

PUZZLE automatically removes jobs that are no longer used. Therefore, PUZZLE manages an expirationTimestamp for each job, which is the earliest point in time at which PUZZLE automatically deletes the job. PUZZLE automatically deletes jobs in any state except state SUBMITTED.

If a job is not used before its expirationTimestamp expires, PUZZLE irrevocably deletes the job automatically at any time after the expirationTimestamp expires. The expirationTimestamp is available in the job's metadata.

Every HTTP Request, with the exception of retrieving the job's metadata, prolong the expirationTimestamp of a job. PUZZLE prolongs the expirationTimestamp after it has computed solutions for that job. A client can explicitly prolong the expirationTimestamp of a job.

Plugins extends the functionality of PUZZLE. Currently, there are two types of plugins: additional representations and importer. You must license plugins separately. The following table lists all available plugins.

Name	Description	Documentation
Overview Image Plugin	Create an image of all the solutions in a job.	Documentation
HTML Export Plugin	Create an interactive HTML 5 document of all the solutions in a job.	Documentation
KPI Plugin	Compute key performance indices for a job.	Documentation
Excel Import Plugin	Import jobs from a Microsoft Excel workbook.	Documentation
Best-Fit Plugin	This plugin provides the Best-Fit optimization mode and provides an own REST API for a clients.	Documentation
Reporter Plugin	Generate reports for solutions.	Documentation

If an error occurred, PUZZLE responses to a client with a HTTP status code and a JSON object as the response body that contains information about the error. The body consists of a JSON object with three attributes: errorMessage contains a description of the error and errorClass contains the full-qualified name of the error (java exception). The attribute additionalInformation contains more information about the error in some cases.

If a defined error of the HTTP protocol occurs, PUZZLE returns the HTTP status code as defined in the HTTP protocol.

For other errors, the following rules applies.

Description	HTTP status code
Client sent malformed JSON and PUZZLE cannot extract job data from the JSON	400
Client request an non-existing job and Client provide job id in the correct format	404
Any other error	500

Error defined in the HTTP Protocol

There are many defined errors in the HTTP, for example, a client requests a non-existent URL. If an error defined in the HTTP protocol occurs, PUZZLE converts the error to the structure described above. PUZZLE responses with the HTTP status code as defined in the HTTP protocol.

For example, if you request an URL that does not exists, such as a jobId in an incorrect format (/puzzle/api/v1/jobs/2ab), PUZZLE responses with HTTP status code 404 and the following body:

    {
      "errorMessage": "HTTP 404 Not Found",
      "additionalInformation": "",
      "errorClass": "jakarta.ws.rs.NotFoundException"
    }

For the url /info PUZZLE only supports the GET HTTP method. When you request for an POST to the url /info, PUZZLE responses with HTTP status code 405 and the following body

    {
      "errorMessage": "HTTP 405 Method Not Allowed",
      "additionalInformation": "",
      "errorClass": "jakarta.ws.rs.NotAllowedException"
    }

Unexpected error occurred

If an unhandled error occurred in PUZZLE, PUZZLE responses with HTTP status code 500, the attribute errorMessage contains the message of the error, the attribute additionalInformation contains the stack trace of the error and the attribute errorClass contains the full-qualified name of the unhandled java exception. In this case, please contact the PUZZLE team.

If a client request violates a precondition, PUZZLE also responses with HTTP status code 500. Examples of this case are given in section 7.

Error occurred while PUZZLE computes solutions

PUZZLE computes solutions for a job asynchronous. Therefore, if an error occurred while computing solutions, PUZZLE cannot return the error message directly to the client. In this case, PUZZLE stores the error message in the attribute errorMessage in the metadata and sets the attribute errorOccurred to true. If no error occurred, errorOccurred is set to false and errorMessage is the empty string.

Enable more detailed logging

If you encounter an unexpected error, you can restart your PUZZLE instance with a more detailed logging.

To achieve this, you must set the log level to debug. To do this, change the file conf/log4j.properties in the installation path of your PUZZLE instance so that it contains the following line:

  log4j.category.de.fraunhofer.iml.puzzle=DEBUG

For the new settings to take effect, you must restart your PUZZLE instance.

The project specific documentation can be found here

This section describes all available HTTP endpoints of the PUZZLE REST API. For each endpoint, this documentation contains an interactive representation of the structure of the request body schema and the response schema below the endpoint description. In addition, the right column contains request and response samples for these structures.

In order to facilitate understanding, the following two scenarios are included as examples.

In this scenario, PUZZLE will compute three solutions how to place an item 8 times on a euro pallet. PUZZLE may exceed the left and right sides of the pallet by approx. 1 cm and the front and rear sides by approx. 2 cm. In addition, the client annotates the job with a customer id by inserting the attribute companyName.customerId to the extension of the job and PUZZLE does not change this attribute.

Images of solutions should show the left and right side of the item should in red (html color code 'FF0000').

In this example, PUZZLE will compute two variants how to place an electronic device twice into a FEFCO 0201 carton. In addition, PUZZLE leave five centimeters of free space on each carton sidewall to facilitate the removal of an item from the carton by a human operator. Therefore, the attributes lengthOverhang and widthOverhang of the loading device entry are set to -50.