Projects

• Last updated on November 11, 2024
• •
• 5 minutes to read

In the context of the Personalization Platform, a project is a reflection of an order that the user makes in e-commerce systems. Projects allow you to save the user changes and personalization results in your Customer's Canvas account by associating the order from the e-commerce system with the user in this system.

Let's look at how you can work with projects using the Storefront API.

Creating projects

When a user creates an order in an e-commerce system, a single project for every line item in the order as well as a project for the entire order can be created in Customer's Canvas.

Projects usually contain:

• The product reference it is based on.
• One or more designs personalized in the editor.
• Information about the item quantity.
• Variable data if needed.
• Other auxiliary data.

The Storefront API provides the following endpoints to create projects:

1. Projects_CreateWithSingleItem creates a project for a singe line item. The pipeline specified in the product configuration will be used. In the request body, you must pass the CreateSingleItemProjectDto data.

2. Projects_CreateByRenderHiResScenario creates a project to perform a single render-hires task for a singe line item. In the request body, pass the CreateProjectByRenderHiResScenarioDto data. Specify the line item in the orderLineItemIndex or orderLineItemId fields. In the scenario object, you can pass the following rendering parameters:

   • designId [string] is an identifier of a private design.
   • name [string] is an output file name, result by default.
   • dpi [integer] is output file DPI, 300 by default.
   • format ["Pdf", "Jpeg", "Png", "Tiff"] is the output file format, "Pdf" by default.
   • colorSpace ["Rgb", "Grayscale", "Cmyk"] is the output file color space, "Cmyk" by default.
   • flipMode ["None", "Horizontal", "Vertical", "Both"] is a flip mode of the output file, "None" by default.
   • anonymousAccess [boolean] is the mode of accessing the output file, false by default.

3. Projects_CreateWithMultipleItems creates a project for many products. The pipeline specified in the product configuration will be used. In the request body, you must pass the CreateMultiItemProjectDto data.

4. Projects_CreateBySpecificPipelineScenario creates a project to process a singe line item or many line items of an order and even the entire order. In the request body, pass the CreateProjectBySpecificPipelineScenarioDto data. In the scenario object, you must specify the pipelines to be applied by name or by ID:

   • pipelineId [integer] is an identifier of an existing processing pipeline, which will be applied to all the items.
   • postProcessingPipelineId [integer] is an existing processing pipeline identifier for project post-processing.
   • itemPipelines [] is an array of objects describing connections between project items (by itemName) and processing pipelines (by pipelineId). Here, you can configure a set of pipelines applicable to different items as an alternative to a single pipeline specified in pipelineId.

For single-item projects, you will need to implement post-processing and additional logic in your client application after receiving the rendering results. For projects that process many items at once, post-processing is already included in the endpoint and when all the artifacts are ready, one of the ordinary actions will be performed, for example, sending an email, uploading results to the client system, or triggering a "completed" event.

Since these APIs do not allow for changing project properties, you can use them to recreate a project and overwrite their properties.

Post-processing pipelines

The post-processing scheme is common to the entire storefront. To configure it through the user interface, in your Customer's Canvas account, navigate to Settings > Integration and click the Project post-processing pipeline drop-down box.

When a pipeline list opens, it displays the pipelines already created in your BackOffice panel. Select one or the option Don't use post-processing pipeline for projects.

When creating projects through the API, you can use the identifiers of those pipelines in the postProcessingPipelineId property.

If you have implemented your post-processing in the client application, this setting will also work. In this case, the pipeline will run additionally.

Project statuses

A project's workflow includes the following project statuses:

• New: every new project gets the New status.
• Confirmed: if the order is correct and paid, you confirm it and move the project status to Confirmed.
• Rejected: when you need to cancel the order processing, you move the project status to Rejected.
• Active: when you start processing the order, you move the project status to Active.
• Completed: when you have fulfilled the order, you can mark the project as complete.

The status of a multi-item project is calculated based on the statuses of processing all its elements, for example, the status will be Active if at least one element is in progress.

You can switch project statuses through both the BackOffice panel and the Storefront API.

To get information about project statuses, you can use the endpoints Projects_GetAllStatuses and Projects_GetAllTransitions. You can switch from one status to another using the Projects_ChangeStatus endpoint, which changes statuses according to the list of their possible transitions.

If you need to forcibly switch the project to an arbitrary status, use the Projects_ForceStatus endpoint.

Browsing projects

To browse projects in your Customer's Canvas account, navigate to the Projects section, where all the projects are listed.

To check the properties of a single project, click an item in this list.

You can do the same through the Storefront API. To retrieve the list of projects from the specified storefront, use the endpoint Projects_GetAll. This endpoint supports filtering by project status, creation date, owner, and other parameters.

The Projects_Get endpoint returns project properties for the specified ID. The main properties are:

• id - the project identifier.
• name - the project name.
• productReference - the product template, i.e., an external reference to a Customer's Canvas product specification.
• storefrontId - the storefront identifier.
• orderId - the order identifier in the e-commerce system.
• orderLineItemIndex - the line item index in the order for which the project was created.
• customerName - the customer name in the e-commerce system.
• status - the project status code.

Rendering print files

The rendering of print files is the most important operation of processing the projects.

When you first open a project in your Customer's Canvas account and click the Download link, the PDF creation process begins. As soon as the file is ready, the PDF download begins.

To generate and download a print file through the Storefront API, use the Projects_GetProjectPdfUrl endpoint.