Loading state files

Last updated on February 19, 2024
•
3 minutes to read

The Preflight Tool allows you to load state files when you are using Customer's Canvas BackOffice to store and process your assets. In this case, you can configure products and create designs in BackOffice. After that, the Preflight Tool loads the resulting templates in the ST format from Asset Storage. The <xref:DesignAtoms API/v1> service plays the role of a bridge between this tool and Asset Storage.

When you open state files in preflight, you don't have to provide bulky product definitions because, along with custom elements such as text and shapes, safety lines with bleed zones and product mockups will be imported from the state file.

In this topic, you will learn how to initialize the driver, set up services, and specify a state file to load.

Auth

We recommend working with the BackOffice Backend API, including the <xref:DesignAtoms API/v1>, by using the StorefrontJS library. This library helps you develop an integration with Customer's Canvas Hub and takes over the authorization.

Driver initialization

In addition to the basic settings of the Preflight driver, provide settings to configure the Design Atoms API service:

apiGatewayUrl is the URL that links to the API Gateway connecting the BackOffice backend services, depending on your hosting environment:
- For the US environment - https://api.customerscanvashub.com
- For the EU environment - https://api.eu.customerscanvashub.com
token is the API access token generated in Customer's Canvas for your storefront user.
tenantId is copied from the Settings > Tenant tab.

The driver initialization with BackOffice settings may look as follows:

// Defining the BackOffice settings.
const boSettings = {
    apiGatewayUrl: "https://api.customerscanvashub.com/",
    token: "<api-access-token>",
    tenantId: <your-tenant-id>
};
// Passing the settings to the driver.
const ecommerce = await driver.init(product, editor, config, settings, null,
                                    quantity, user, boSettings);

Backend reference

By default, the preflight widget uses the back end on the same server where you have deployed the distribution package. To link it with your BackOffice tenant, define the URL that links to the Preflight application specified in the Settings > Applications tab.

"vars": {
    "backendUrl": "https://cc-apps.aurigma.net/1172/preflight/1.25.0"
},
{
    "name": "preflight",
    "type": "preflight",
    "params": {
        "config": {
            "backendUrl": "{{vars.backendUrl}}",
            ...

In this example, we define backendUrl in the config file. As an alternative, you can pass variables when initializing the driver as follows:

// The configuration of the Preflight Tool.
const config = await moduleLoader.loadJson("./config.json");
// The address of your back end.
config.vars.backendUrl = "https://cc-apps.aurigma.net/1172/preflight/1.25.0";

State identifier

To load a state from Asset Storage, specify its ID in the state object as follows:

"vars": {
    "design": "64f6d1be473213417c7a54a4"
},
"widgets": [{
    "name": "preflight",
    "type": "preflight",
    "params": {
        "config": {
            "state": {
                "stateId": "{{ vars.design }}"
            },
            "product": {
                "allowAddPages": true,
                "allowDeletePages": true
            },
            ...
        }
    }
}]

After configuring the state file to download, most settings defined in the product object, if any, will be ignored, and only the following settings will be applied:

allowAddPages
allowDeletePages
dpi

Other product parameters, such as size, bleed, slug, etc., will be taken from the loaded state.

Services

When configuring a workflow in BackOffice, you can't provide the input to the driver. In this case, specify the required BackOffice settings in the services object of the preflight widget config as follows:

{
    "name": "preflight",
    "type": "preflight",
    "params": {
        "config": {
            "backendUrl": "{{vars.backendUrl}}",
            "services": {
                "designAtoms": {
                    "url": "https://api.customerscanvashub.com/",
                    "token": "{{vars.apiAccessToken}}"
                },
                "tenantId": "{{vars.tenantId}}"
            }
            ...

Limitations

In the current implementation, only text elements, shapes, and their groups are loaded into the Preflight Tool.

To be able to load text in this way, you must first import the used fonts into your tenant.

Other elements may disappear after loading the state file. If you face a problem while loading state files, make sure that they do not contain images.