View as Markdown
You’re viewing outdated documentation. View the latest Customer’s Canvas On-Premises documentation.

State Files

Applies to: Customer's Canvas On-Premises; Design Editor 4.4.25, 4.x (may differ) · Archived documentation

Every time you call saveProduct or finishProductDesign, Customer's Canvas creates a state file representing all objects loaded in the editor. By default, these state files are saved in the ~\UserDataFolder\<someUserId>\states\ folder for a single user and they are kept forever until you delete these files manually. Customer's Canvas does not automatically clean them up. At the same time, you can use the Web API to manipulate state files in your application: list available state files, delete state files, or reload images in state files from their original sources.

This API works based on HTTPS requests and is handled by the StateFiles controller with the following methods:

Function Request type URL
Get a list of user's state files GET ~/api/users/{userId}/states
Download a user's state file GET ~/api/users/{userId}/states/{stateId}
Delete a user's state file DELETE ~/api/users/{userId}/states/{stateId}
Copy and clone a state file POST ~/api/users/{userId}/states/{stateId}
Modify a state file PATCH ~/api/users/{userId}/states/{stateId}
Get product tags from a state file GET ~/api/users/{userId}/states/{stateId}/tags

URL Parameters

The StateFiles controller requires the following parameters:

  • userId=[string] - a user identifier.
  • stateId=[string] - a file name of a state without an extension.

Error Response

This controller can return the following errors:

  • Status Code: 403 Forbidden
Content: HTTPS Required
  • Status Code: 403 Forbidden
Content: Invalid Security Key
  • Status Code: 404 Not Found
Content: The specified state file cannot be found.
  • Status Code: 400 Bad Request
Content: This state already exists.
  • Status Code: 500 Internal Server Error
Content: The remote server returned an error: (404) Not Found.

It is recommended to download a code sample written in ECMAScript 2015 that demonstrates how you can work with the API and refer to this sample when reading this topic.

Important

The security model of Customer's Canvas requires you to pass X-CustomersCanvasAPIKey in request headers. The snippets below define the API security key in JavaScript code. It could be highly insecure if it runs on a public site. However, you can use it this way in your admin panel, or just for demonstration purposes.

Getting a List of a User's State Files

Request Example

JavaScript 
const userId = "default";
const url = `https://localhost:44300/api/users/${userId}/states`;
fetch(url).then(response => {
    return response.json();
}).then(json => {
    for (let i = 0; i < json.length; i++) {
        const s = json[i];
        console.log(s.stateId);
    }
});

Success Response

For example, you will get the following response for the case when the default user has a state file.

Status Code: 200 OK
Content:
[{
  "stateId":"0777bb82-6f89-4e72-93b1-aad1b875602b",
  "dateModified":"5/26/2018 8:29",
  "surfaceCount":2,
  "tag":null
}]

Downloading a User's State File

Request Example

JavaScript 
const userId = "JohnWood";
const stateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}`;
logElement.textContent = "init request";

fetch(url, {
    method: "GET",
    headers: {
        "X-CustomersCanvasAPIKey": "UniqueSecurityKey",
        'Accept': 'application/json',
        "Content-Type": "application/json"
    }
})
.then(
    response => {
        if (response.ok) {
            console.log("The state file was downloaded successfully.");
            console.log(response.url);
        }
        else
            console.error("Failed to download the state file.");
    },
    e => console.error("Failed to download the state file.")
);

Success Response

If the result is successful, this API returns a file stream:

Status Code: 200 OK
Content-type: application/octet-stream

Deleting a User's State File

To delete a saved product, you can make the following request.

Request Example

JavaScript 
const userId = "JohnWood";
const stateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}`;
fetch(url, {
        method: "DELETE",
        headers: {
            "X-CustomersCanvasAPIKey": "UniqueSecurityKey",
            "Content-Type": "application/json"
        }
    })
    .then(
        response => { return response.json(); },
        e => console.log("Failed to delete the state file.")
    )
    .then(json => {
        if (json === true)
            console.log("The state file was deleted successfully.");
        else if (json === false)
            console.log("Requested state file is not found.");
    });

Success Response

If the result is successful, this API can return the following:

  • The state file was not found.
    Status Code: 200 OK
Content: false
  • The state file was deleted successfully.
    Status Code: 200 OK
Content: true

Copy and Clone a State File

Request Payload

To copy state files, you need to pass the following parameters in the request body:

  • UserId=[string] - an identifier of the user whose file you want to copy.
  • StateId=[string] - an identifier of the state file you want to copy.
  • Overwrite=[boolean] - allows for overwriting state files.
json 
const parameters = {
    "CopyFrom": {
        "UserId": "sourceUserId",
        "StateId": "sourceStateId"
    },
    "Overwrite": true
};

Note that userId and stateId in the request URL are the destination identifiers.

Request Example

JavaScript 
const userId = "JohnWood";
const stateId = "Invitation";
const sourceUserId = "masteruser";
const sourceStateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}`;
const parameters = {
    "CopyFrom": {
        "UserId": sourceUserId,
        "StateId": sourceStateId
    },
    "Overwrite": true
};
fetch(url, {
        method: "POST",
        headers: {
            "X-CustomersCanvasAPIKey": "UniqueSecurityKey",
            "Accept": "application/json",
            "Content-Type": "application/json"
        },
        body: JSON.stringify(parameters)
    })
    .then(
        response => {
            if (response.ok)
                console.log("The state file was copied.");
            else
                console.log("Failed to copy the state file.");
        }
    );

Success Response

When a state file has been successfully copied, this controller returns:

Status Code: 204 No Content

Modify a State File

The StateFiles controller allows you to modify state files. You can specify product tags and update images obtained from external sources through direct URLs.

After your end users have added images through the Asset Manager, the original files may be changed. If the application requires those changes to be applied to saved state files, you can use this Web API method. This method will trigger Customer's Canvas to download new versions of these images and will replace them in the state file. Reloading images invalidates preview and hi-res links in the cache, thus they are recreated based on the new versions of these images when the application requests them next time.

If the original image has been edited so that its dimensions have changed, then the new image is arbitrarily resized to fit into the old bounds when reloading this image. If any of the original images are deleted, the controller returns the 500 Server error and does not reload images.

Request Payload

The PATCH request expects the type property in the request body. You can define one of the following values:

  • MemorySourceReloadAll reloads all images in a state file.
  • PatchImageItems replaces Depositphotos previews with purchased images. This parameter additionally requires links to the purchased images. For an example, refer to the Depositphotos Assets topic.
  • PatchProductTags defines product tags. This parameter additionally requires a JSON structure or an array. After you have defined new tags for a product, old tags are discarded.

When you use product tags for personalized rendering, you can organize them in an array so that each element represents a data set to render an output image. The data set, in turn, is an array of objects defining how a single field should appear in the hi-res output. For example, you can define the data to render two product copies with predefined values of the Name, Photo, and Barcode elements as follows:

JavaScript 
const data = [
    [
        { name: "Name", value: "Neo", type: "InString" },
        { name: "Photo", value: "https://example.com/Neo.jpg", type: "ImagePlaceholder" },
        { name: "Barcode", value: "1234567", type: "BarcodePlaceholder", barcodeFormat: "EAN-8" }
    ],
    [
        { name: "Name", value: "Trinity", type: "InString" },
        { name: "Photo", value: "https://example.com/Trinity.jpg", type: "ImagePlaceholder" },
        { name: "Barcode", value: "7654321", type: "BarcodePlaceholder", barcodeFormat: "EAN-8" }
    ]
];

Such an object may define the following properties:

  • name: string - the element name on the canvas.
  • value: string - either text or link to an iamge.
  • type: string - the design element type, one of "Image" | "ImagePlaceholder" | "Text" | "InString" | "BarcodePlaceholder".
  • barcodeFormat: string - the applicable barcode format, one of "EAN-8" | "EAN-13" | "QR-CODE".
  • barcodeSubType: string - the barcode sub type, one of "Phone" | "Url" | "None".

Example of Reloading Images

JavaScript 
const userId = "JohnWood";
const stateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}`;
fetch(url, {
        method: "PATCH",
        headers: {
            "X-CustomersCanvasAPIKey": "UniqueSecurityKey",
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            type: "MemorySourceReloadAll"
        })
    })
    .then(
        response => {
            if (response.ok)
                console.log("Images were reloaded successfully.");
            else
                console.log("Failed to reload images.");
        }
    );

Example of Specifying Product Tags

You can set product tags as follows:

JavaScript 
const userId = "JohnWood";
const stateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}`;
const data = {"product": "postcard", "design": "flowers", "colorTheme": "red"};

fetch(url, {
    method: "PATCH",
    headers: {
        "X-CustomersCanvasAPIKey": "UniqueSecurityKey",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        type: "PatchProductTags",
        data: data
    })
});

Success Response

When a state file has been successfully patched, this controller returns:

Status Code: 204 No Content

Get Product Tags from a State File

To retrieve product tags, you can make the following request.

Request Example

JavaScript 
const userId = "JohnWood";
const stateId = "1f190673-226d-4c31-87b4-0140805cc445";
const url = `https://localhost:44300/api/users/${userId}/states/${stateId}/tags`;

console.log(await (await fetch(url, {
    method: "GET",
    headers: {
        "X-CustomersCanvasAPIKey": "CustomerSecurityKey",
        "Content-Type": "application/json"
    }
}).json));

Success Response

For example, you can get the following response.

Status Code: 200 OK
Content:
{"product": "postcard", "design": "flowers", "colorTheme": "red"}

See Also

Manual

Downloads