UNILIN-UNIMAT

This section describes the UNILIN-UNIMAT interface used with Q-Cloud.

The page structure follows the old source document closely, but the business interpretation matches the current interface implementation. The file structure in this documentation is unchanged: overview, control records, wearers, garments, uniforms, messages, rules, and legacy-difference notes remain separate pages.

General Description

The interface is:

  • record-oriented

  • ordered

  • delta-based

  • device-driven

Each row contains one mutation code. Mutation 0 starts a new control block. Data can contain rows for more than one device in the same payload.

For the current interface, device identity is authoritative. For each row:

  • the device number is resolved first

  • the customer is taken from the device ownership

  • that customer scope is then used for wearer, garment, article, and uniform handling

This interface accepts the recommended initialization sequence 1,2,A,C when a file introduces wearers, garments, uniforms, and uniform articles in one ordered payload.

Customer values present in the source row remain descriptive input, but they do not override the customer resolved from the device.

For garment rows, Q-Cloud keeps the legacy split between personal garments and generic garments, but the current interface handles both through the same device-derived customer scope:

  • personal garments resolve to wearers in that customer

  • generic garments resolve to item pools in that customer

  • article codes are resolved in the same customer scope, and missing articles can be introduced there as part of garment handling

Device And Customer Resolution

The interface starts from the device in the row.

The device number is identified first. The interface then determines which customer that device belongs to. That customer is used as the customer scope for the row.

This means:

  • wearer data is handled in the customer that owns the device, and T.1 / T.5 behave as wearer upserts in that scope

  • garment data is handled in the customer that owns the device

  • article data is handled in the customer that owns the device

  • uniform data is handled in the customer that owns the device

The customer number present in the source row may be retained as descriptive information, but it does not decide scope or ownership.

Processing Outcomes

The pages in this section use a small set of outcome terms consistently:

  • executed: the row causes a business change in Q-Cloud

  • no-op: the row is recognised and valid, but it does not change business state because the desired state already exists or the target is already absent

  • warning-only: the row is recognised, logged, and accepted as part of the file format, but the current release does not apply a business change for that mutation

  • invalid: the row cannot be applied because required identities, dependencies, or preconditions are missing

  • error: the overall payload or run is failed because one or more invalid rows or structural problems were encountered

Mutation Codes

The mutation codes sent from the laundry side are:

Code Record type Current release note

0

Control record

-

1

New wearer

-

2

Assign garment to wearer

-

3

Bring garment back from device

-

4

Delete garment from device

-

5

Change wearer information

-

6

Add signal to garment

Recognised by the interface, but currently not business-enabled.

7

Delete wearer

-

8

Garment for loading / outscan

-

9

Garment delivered to wearer

Recognised by the interface, but currently not business-enabled.

A

Add new uniform

-

B

Delete uniform

-

C

Add article to uniform

-

D

Delete article from uniform

-

E

Message to wearer / general message

Recognised by the interface, but currently not business-enabled.

F

Change garment information

Existing garments are updated; missing garments are created from the row data.

G

Change article code

-

H

Reserved

Recognised by the interface, but currently not business-enabled.

Identity And Scope

The current interface uses the following identities:

  • device identity: UNIMAT / device number in the row

  • customer identity: resolved from device ownership

  • wearer identity: administration no within customer scope

  • garment identity: chip number

  • article identity: customer-scoped article code

  • uniform identity: customer-scoped uniform number

Uniforms are represented as customer-scoped credit-limit templates in the current interface.

Wearer rows 1 and 5 use administration no as the wearer key in that customer scope. If the wearer already exists, the row updates it; otherwise the row creates it. If the row carries a uniform number, the wearer is linked to the corresponding uniform when it is already present or when that uniform is introduced later in the same file.

Identity Mapping

To make the old field names easier to read in Q-Cloud terms:

  • administration no → wearer identity within the resolved customer scope

  • uniform number → uniform identity, implemented as a credit-limit template external identity in that customer scope

  • chip number → garment identity

  • article code → article identity within the resolved customer scope

Personal And Generic Garments

The old source document described both personalised and generic garments. That distinction still exists.

In the current interface:

  • a personal garment is connected to a wearer

  • a generic garment is connected to an item pool

  • the distinction is made by comparing administration no with the configured generic-user identity

This keeps the legacy business concept while matching the current handling.

The configured generic-user identity is the special administration no value that marks a row as generic instead of personal. When a garment row uses that value, the row is handled against item pools instead of wearers.

What Happens When A Row Is Processed

For each incoming row:

  1. The mutation code is read.

  2. The device number is resolved.

  3. The customer scope is derived from the device.

  4. The row is interpreted according to the matching record definition.

  5. Ordering and dependency rules are enforced.

If required identities are missing or the dependency order is wrong, the payload is treated as invalid for that operation.

Some recognised mutation codes are intentionally warning-only in the current release. They remain part of the supported file format, but they do not change Q-Cloud business state:

  • 6 Add signal to garment

  • 9 Garment delivered to wearer

  • E Message to wearer / general message

  • H Reserved

What The Interface Ensures

The interface preserves the meaning of the ordered delta stream.

The following is ensured:

  • rows are interpreted in the order in which they are received

  • a later row is never interpreted as if it had happened before an earlier row

  • control-record boundaries are respected

  • each row is handled in the customer scope determined from the device for that row

  • later rows are evaluated against the state created by earlier valid rows in the same payload

  • recognised warning-only mutation codes remain distinct from malformed input

The interface is not a full replacement import. It remains a delta interface.

Record Families

The detailed interface description is split across these pages: