• In this version PUZZLE ignores the attribute heightOverhang in loading devices. A client can set a value and it is stored in the internal representation of a job, but PUZZLE does not evaluate this attribute in the computation of solutions
• The version tag in the URLs has remained to v1 for version 2.0.x, due to the URLs of the endpoints has not changed. You can retrieve the installed version of the REST API through the /info endpoint

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. Each entry in the list of orderlines has a unique orderLineNumber, a maximum quantity and the master data describing the ordered item or stock keeping unit (SKU). During optimization, PUZZLE will not exceed the given quantity for any entry in the list of orderlines.

The attribute loadingPriority denotes the sequence (order) in which PUZZLE consider order lines. PUZZLE divides the Orderlines into groups, each containing all Orderlines with the same value for the attribute 'loadingPriority'. PUZZLE considers these groups in ascending order of their values for the 'Order' attribute. OrderLines with the value null for the attribute loadingPriority can be set at any time PUZZLE may omit the attribute loadingPriority in JSON representations of a Job. It will always be present if the value of loadingPriority is not 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.

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

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 supported cartons or pallets in a similar manner. Loading devices have the following attributes in common:

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:

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.

A solution contains the following data.

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:

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.

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.

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.

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

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.

Pallet example

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').

Carton example

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.