...

Publisher Package

A CHILI Package is a standalone file format , which can be used to represent a CHILI Publisher Document for import (in the same or another environment, or even on another server).

Internally, the CHILI Package is a zip file, containing several files describing the layout and content of the document.

General structure

A CHILI Package contains (in the root of the zip file):

• Asset_Previews: Optional directory containing low-res previews of any assets contained in the package. Underneath the "Asset_Previews" folder, the same directory structure as "Assets" should be present. Previews will be included with the same file name as the original asset, but with a ".png" extension

• Assets: Folder structure containing the high res (original) files used in Image Frames, including the directory structure under which the assets will (by default, although this can be overriden during import of the package) be placed within the CHILI server

• Fonts: a similar folder structure, containing the font files used within the document (.otf or .ttf)

• Document_Previews: Optional directory containing a "preview.pdf" file containing a first (initial) preview file for the CHILI document

• assets.xml (see lower)

• fonts.xml (see lower)

• document.xml (see lower)

assets.xml contains a description of all of the images/assets to be used in the CHILI document. It contains the following structure:

<assets defaultLocation="Exported\ExtensionTest\Untitled-1">
   <item id="99ACED82-4BBE-1E9E-A5AC-7A8FFA4EDBA0" file="Assets\Exported\ExtensionTest\Untitled-1\boober1.jpg" relativePath="Exported\ExtensionTest\Untitled-1\boober1.jpg" name="boober1.jpg"/>
</assets>

Where:

• assets/@defaultLocation contains the "default" path of new assets inside CHILI, when the package is being uploaded using ?Webservice Functions - DocumentCreateFromChiliPackage

• item/@id contains the ID of the asset, as it is refered to inside the document.xml file

• item/@file contains the path of the source file, starting from the root of the package's zip file

• item/@relativePath contains the default path of the asset once uploaded to CHILI

• item/@name contains the file name of the underlying image

fonts.xml contains a description of all of the fonts to be used inside the CHILI document. It contains the following structure:

...

across different environments or servers. These packages contain the document XML, font files, and assets applied to frames, enabling seamless transfer and reproduction of CHILI Documents.

Contents and Limitations

CHILI Packages include:

• Document XML

• Font files (both assigned and unassigned)

• Assets applied to frames

CHILI Packages do not include:

• Changes to image assets via actions

• Assets stored in variables but not assigned to frames

• Barcodes Types

• PDF Export Settings or any output settings

• Dynamic Asset Providers settings

• DataSources Settings

Size Limitations

While you can output a package of any size, CHILI GraFx supports a maximum of 1 GB package size when you import it back into Publisher.

Package Structure

The CHILI Package is a zip file with a customizable extension. You can change the extension in the System → GraFx Publisher Management settings.

The structure typically includes:

package_name.zip/
├── assets.xml
├── document.xml
├── fonts.xml
├── meta.xml
├── Assets/
└── Fonts/

assets.xml

This file is a manifest for all assets in the Assets folder. Example:

<assets defaultLocation="Assets\Imported\example doc">
  <item id="836abf47-4f62-4f0d-a2c7-a402a295b6fe" oldID="5536ff25-2a77-434a-865e-065d5371fdb7" file="Assets\Imported\example doc\example.jpg" />
</assets>

Key points:

• Asset names are changed to random GUIDs with a ".asset" extension during packaging.

• The document.xml is modified to use the new GUID.

• The id property matches the externalID property in the modified document.xml. This ID should be relied on to be the same after import.

• The oldID is the original Asset file ID in the BackOffice.

• The file property indicates where the asset will be uploaded in the BackOffice if no other value is provided during import. This value is hardcoded to be Imported\{document name}\{file name}

fonts.xml

This file is a manifest for all fonts in the Fonts folder. Example:

<fonts defaultLocation="General\FromInDesign">
   <item<item id="700b444b-6941-464f-bff8-8028cac221a9" file="\Fonts\General\FromInDesign\MinionPro-RegularAkzidGroProBol.otf" />
  <item id="F4AEE4093a229c16-A8920c81-607046fb-498E8ebd-7A8FF0113D03d5ea5cd67f41" />
</fonts>

where:

• fonts/@defaultLocation contains the "default" path of new fonts inside CHILI, when the package is uploaded

• item/@id contains a unique ID, which is used inside document.xml to reference to the font

• item/@file contains the font's underlying file path, relative from the root of the package's zip file

document.xml is a valid CHILI XML document (following the normal XML guidelines and rules), with the following exceptions:

...

Any reference to an asset in the imageframe's "externalID" attribute points to an ID used in assets.xml

...

ImageFrames do not require metadata about the placed asset (realWidthPixels, realHeightPixels, metadata, ...). This information will be populated by CHILI when importing the Package on the server

...

Any reference to a font should use the ID used in fonts.xml

...

Key points:

• Font files are renamed to match the font element ID in the document.xml with a ".font" extension.

• The id property is the ID of the font element in the document.xml and the name of the renamed font file.

• The file property indicates where the font will be uploaded in the BackOffice if no other value is provided during import. This value is hardcoded to be General\FromInDesign\{file name}

• An item element with no file property represents the default Arial font.

document.xml

This file contains the actual document XML, slightly modified from the original. Specifically, the externalID property of image frames is changed to match the new asset GUIDs.

meta.xml

This file is used for transporting metadata, most commonly the name of the document.

Managing Packages

Packages can be uploaded via:

• BackOffice

• Adobe® plugin or extensions

• DocumentCreateFromChiliPackage API - POST /rest-api/v1.2/resources/documents/frompackage

When uploading a package, you can define the folder location for uploaded Assets or Fonts.

If you don't define a location, default locations will be used as defined in the fonts.xml and the assets.xml files.

• Fonts: General\FromInDesign\{file name}

• Assets: Imported\{document name}\{file name}

Best Practices

Font Management

It's strongly recommended to:

• Change the font location to the same static folder path when importing packages.

Benefits:

• Prevents duplicate fonts

• Saves storage space

• Ensures use of verified, working fonts - as it is possible for someone to upload a corrupt font or for the font to become corrupt during unzipping

This approach assumes that font names are consistent amongst users, which is what we also find in looking at usage. However, in systems that utilize a lot of different fonts and designers without strict font requirements, you will still have a small percentage of duplicate fonts due to the font file names being different.

Asset Management

It's strongly recommended to:

• Change asset location to a unique folder path when importing packages

This approach prevents accidental ignoring of unique assets that happen to share the same file name. For example, someone uses an image called “headshot.png” and when they import the package, there may already be another “headshot.png” from a completely different designer. Clearly, you want both copies, and you don’t want to replace the package file with the already existing file. Thus, it is prudent to use unique folder pasts with assets.

However, please create a cleanup strategy to clean up old unused assets.