Information Classification: External Restricted.
See https://www.chili-publish.com/security

CHILI Package file format

Owned by Bram Verniest (Unlicensed)
Last updated: Jun 24, 2024 by Sean Crowe
4 min read

Publisher Package

A CHILI Package is a standalone file format used to represent a Publisher Document for import 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

 

Note: The object IDs of exported fonts and assets found in the BackOffice are not maintained after package import.

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.

 

Warning: Never modify or rely on this structure directly, as the behaviors may change without notice.

 

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 id="700b444b-6941-464f-bff8-8028cac221a9" file="Fonts\General\FromInDesign\AkzidGroProBol.otf" /> <item id="3a229c16-0c81-46fb-8ebd-d5ea5cd67f41" /> </fonts>

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.

In the API call, use the query properties:

  • newAssetLocation

  • newFontLocation

For example:

http://cp-xyz-123.chili-publish-sandbox.online/rest-api/v1/resources/documents/frompackage?documentName=example&folderPath=temp&newAssetLocation=importAssets&newFontLocation=importFonts

 

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}

 

Important: If the path contains a file with the same name, the new file from the package will not be added. Instead, the document XML will be modified during import to utilize the file already in the BackOffice.

If the file name is unique, the new file from the package will be added to the BackOffice with a new ID and the document XML will be modified during import to utilize the new ID.

 

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.

 

All information on this page must be treated as External Restricted, or more strict. https://www.chili-publish.com/security