XML files need to have a single root element and in the case of integration with LabelHub the naming of the root element is used to determin what type of entity is in the file. There are multiple rootnames/entities available, e.g:

• brandowner
• die
• label
• material
• lacquer
• etc

The encoding in the prolog-element is used to determin the encoding for the import. It is highly recommended to use UTF-8 as encoding since it is the only one LabelHub official support.

Sample of XML-file format illustrating the prolog and a die rootelement

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<die version="3">
  ...
</die>

It is possible to send multiple entities in one file by sending them in one "package". This can be useful when there are dependencies, like a dependency from a Label to a BrandOwner, Die, Material or similar. LabelHub will automatically import entities inside a package in the correct order to ensure dependencies resolve correctly during import. It is possible to send all types of LabelHub XML commands and entities in a package as the package is just a wrapper of multiple XML-files. Please note that importing packages are NOT an atomic nor idempotent operation! So while some(or all!) of the entities/commands in a package fail to import, the package will be marked as "successfull" if the package itself is parsable. This can make debugging issues problematic, so only use packaging when dependencies are required to resolve correctly, otherwise single entity files are prefered!

Packaging in LabelHub are simple, it is simply a root wrapper named labelhubpackage around the entities. So a simple example would be:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<labelhubpackage>
  <label version="6">
    ...
    <dieNo>123</dieNo>
    ...
  </label>
  <die version="3">
    <number>123</number>
    ...
  </die>
</labelhubpackage>

Here there is a dependency from the label to the die with dienumber 123. In this case LabelHub will first import the die-section, because of the dependency, and afterwards import the label-section.

Please refer to the rest of the documentation for each of the different types of entities.

LabelHub uses a versioning system of the XML-structure to make integrations more resilient. A new version is introduced when a breaking change are made, eg. renaming a field. The versioning is done via the version-attribute on the root element. Each entity type has it's own series of versionnumbers.

It is always recommended to use the latest version, but older versions will be kept working as long as possible(and as long as someone uses them). If a very old version is used LabelHub might contact you and help you upgrade to a newer version.

Some entities uses floating point numbers and in order to ease formatting of those, it is possible to override decimal- and/or thousandsseperators. This is also done as an attribute on the root element.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<label version="3" decimalsep="," thousandsep="." >
  ...
  <width>117,5</width>
  ...
  <labelsForward>1.000</labelsForward>
  ...
</label>

The default decimal seperator is a period/full stop. The default thousandsseperator is none/empty. An example of a default number would be 1234.56.

If possible it is recommended to use the default and not override the seperators.

The name of the files sent to LabelHub does not have any technical effect on the import itself. The only requirment is that the files have the .xml-extension. However, it is our experience that naming the file with the pattern {entityType}_{primarykey}.xml(eg. label_1234.xml) makes things easy to debug in case of issues. Another option is to add a timestamp to make them unique (eg. {entityType}_{primarykey}_{epochtimestamp}.xml => label_1234_1646736715.xml).

If possible it is recommended to use add some sort of random number or timestamp to the end of the filenames to make sure they are unique.