Rendering through the Personalization Platform

• Last updated on December 20, 2024
• •
• 23 minutes to read

This article describes how you can render private designs obtained from an editor and convert them to PDF or other print files via the cloud rendering service of the Personalization Platform. The rendering service provides with a robust queue manager for handling output PDFs and serving them over FTP or invoking by URL.

Assumptions

Assumptions used in this guide:

• You have access to a Customer's Canvas account.

• You have registered storefront.

• You have registered users.

• You have created a page with an editor, which returns state files.

• You have learned how authentication and API clients work in Customer's Canvas:

  • Official API clients
  • Example of using the C# API Client

Rendering print-ready files

Let's suppose you have received an output from the Handy Editor or the Design Editor, which contains, among other things, a private design ID.

To render print-ready files, you need to create a project that runs a rendering pipeline and stores private designs, outputs, data obtained during personalization, and order details.

There are three approaches to using pipelines:

• Built-in pipeline

  When you only need to get a print file for a design, you can create a project with a built-in pipeline through the endpoint /api/storefront/v1/projects/by-scenario/render-hires.

• Custom pipeline

  Another approach is preparing a rendering pipeline. Use this approach when you need not only render a design, but also perform post-processing, like sending a file or making additional operations. Create a pipeline and use it in the endpoint /api/storefront/v1/projects/by-scenario/specific-pipeline.

• PIM product pipeline

  When using the PIM module, you can use the pipeline linked to the PIM product. To identify the pipeline, you will need to pass a storefront product reference. To create a project, call the endpoint /api/storefront/v1/projects/with-single-item.

Projects start the rendering process immediately after they are created. Since this is an asynchronous process, you need to poll the project status to get artifacts (i.e. print files), as explained in the Downloading artifacts article.

As an alternative to polling the project, you can create a pipeline with an invoke-url task to send the resulting artifacts to the specified URL once the job is complete.

To learn how to create PIM products, refer to the Creating products tutorial.

Examples

PDF rendering in CMYK at 300 DPI

Generating high-resolution files does not always require explicitly creating rendering pipelines.

In the simplest case, when you only need to get a print file for a design, you can create a project with a built-in pipeline that performs a single render-hires task. To do so, use the endpoint /api/storefront/v1/projects/by-scenario/render-hires.

In the following example, you may learn how to create a project and then extract the print file. Let's render a design with ID 62da200abb25c5477797d9cb linked to storefront 12 to the file print.pdf.

• cURL
• HTTP
• C#
• TS
• PHP

# First, send this request.

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "scenario": {
       "designId": "62da200abb25c5477797d9cb",
       "name": "print"
    }
  }'

# Then, poll the project's status to see if it is completed or failed.
# For example, if the project ID is 4657, send this request
# and wait for the Completed or Failed status. 

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/processing-results" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

Depending on the design size, the rendering process may take some time. Therefore, you will not get the result immediately, but will need to monitor the progress of the project. To poll the project's status, use the project ID provided in the response. The status can be obtained through the endpoint /api/storefront/v1/projects/{id}/processing-results as described in the topic Downloading artifacts for an order. Keep polling until the status becomes "Completed".

The mandatory parameters for this endpoint are the storefront ID, the design ID, and ID of this design owner. So, you can pass this minimal set of parameters as follows:

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "scenario": { "designId": "62da200abb25c5477797d9cb"}
  }'

If you need to track the result in your Customer's Canvas account, specify the project's ownerId the same as the design's ownerId.

In the request body, you can pass the scenario object with the following rendering parameters:

• designId is an identifier of a private design.
• name is an output file name without the extension, "result" by default.
• dpi is output file DPI, 300 by default.
• format is the output file format, "Pdf" by default.
• colorSpace is the output file color space, "Cmyk" by default.
• flipMode is a flip mode of the output file, "None" by default.
• anonymousAccess is the mode of accessing the output file, false by default.

The access mode defines how you can download the output files. Depending on your purpose, you can use them within your application or send them to a third-party system. Therefore, you may apply authentication or not when downloading files from the resulting link. This is how you can grant anonymous access to print files via a link.

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "scenario": {
       "designId": "62da200abb25c5477797d9cb",
       "anonymousAccess": true
    }
  }'

Custom pipelines with invoke-url

The built-in pipeline may not be enough for you. In this case, you can create a pipeline in the Customer's Canvas admin panel. You can find the details on how to do this in the How to create pipelines tutorial.

For our purpose, a pipeline may consist of the following steps:

• extract-project-design - adds a design file to a pipeline
• render-hires - renders a PDF artifact at a resolution of 200 DPI
• configure-access - makes it possible to download PDF anonymously
• invoke-url - transfers files to an external address
• finalize - marks the specified artifacts as final and removes all temporary data.

{
    "tasks": [
        {
            "description": "Extract design from project",
            "name": "extract-design",
            "type": "extract-project-design",
            "parameters": {},
            "outputArtifacts": [
                "design"
            ]
        },
        {
            "description": "Render design",
            "name": "render-print-file",
            "type": "render-hires",
            "inputArtifacts": [
                "design"
            ],
            "parameters": {
                "hiResOutputDpi": 200
            },
            "outputArtifacts": [
                "result"
            ]
        },
        {
            "description": "Configure print file access",
            "name": "configure-access",
            "type": "configure-artifacts",
            "inputArtifacts": [
                "result"
            ],
            "parameters": {
            "anonymousAccess": "true"
            }
        },
        {
            "description": "Print file delivery to cloud storage",
            "name": "delivery",
            "type": "invoke-url",
            "inputArtifacts": [
                "result"
            ],
            "parameters": {
                "url": "https://example.com/savefiles",
                "httpMethod": "POST",
                "queryHeaders": {
                    "x-api-key": "abc123"
                },
                "body": {
                    "projectId": "{{project.id}}",
                    "orderId": "{{project.orderId}}",
                    "url": "{{result:url}}"
                }
            }
        },
        {
            "description": "Finalize",
            "name": "finalizing",
            "type": "finalize",
            "finalArtifacts": [
                "result"
            ]
        }
    ]
}

To deliver the project results, you need to implement a simple web interface that accepts a request from the pipeline and specify its URL in the invoke-url task. After that, it's enough to just create a project. When the pipeline has finished, you will receive a request on the web interface that you have specified. In this request, you will pick up the rendered artifacts.

You can open the Projects section in your Customer's Canvas account and control how the pipeline is created and executed, which may be important when you are just setting it up.

To create a project, use the endpoint /api/storefront/v1/projects/by-scenario/specific-pipeline. In the request body, pass the ownerId, orderId, items.designIds, and the ID of your processing pipeline in scenario.pipelineId. You can find the pipeline ID in the address bar when editing a pipeline.

Let's render a design with ID 62da200abb25c5477797d9cb by using a pipeline 247.

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "orderId": "1004",
    "ownerId": "6527afc635b52bfadd355226",
    "items": [{
        "designIds": ["62da200abb25c5477797d9cb"]
    }],
    "scenario": { "pipelineId": 247 }
  }'

Instead of using webhooks in invoke-url, you may want to add the upload-to-ftp or send-email tasks to provide the results. For a better understanding of pipelines and for a full specification of the pipeline format, refer to the Order processing pipelines documentation.

To learn how to deliver results to your system and process many designs within a request, refer to the Processing personalization results topic.

Pipelines of PIM products

If you have created a PIM product and need to render its designs, you can use the pipeline linked to that product by product reference.

You can define a processing pipeline when editing or creating a PIM product. In your Customer's Canvas account, open Projects, click Edit or Create new, click the Processing pipeline drop-down box, and select a pipeline. Note that the pipeline must already be created in your account.

For more details about creating PIM products, refer to the Creating PIM products topic. For more details about crating pipelines, refer to the How to create pipelines tutorial.

To create a project, call the endpoint /api/storefront/v1/projects/with-single-item and pass a model there. For example, the model to render a design '62da200abb25c5477797d9cb' by using a pipeline specified for the product '24297' may look as follows:

{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"]
    }
}

The request will look as follows:

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/with-single-item?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"]
    }
  }'

Note that you need to poll the project's status to see if it is completed or failed as described in the previous example.

Rendering multiple line items

You can render multiple products in a project. These can be products the user has added to a cart, and you can process the entire order in one project. You can use the endpoint /api/storefront/v1/projects/with-multiple-items to create such a project and link pipelines by product reference.

Let's create a project to render two products. The first product has one design '642e793dc46d098d64514607', while another has two designs '642d0e469793dc8d64460751' and '62d777a20cbbb25c5497d0a9' to render. Their owner ID is '6527afc635b52bfadd355226'. To link pipelines, we pass their product references '24298' and '24299'.

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/with-multiple-items?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "orderId": "1004",
    "ownerId": "6527afc635b52bfadd355226",
    "items": [{
        "orderLineItemIndex": 0,
        "productReference": "24298",
        "designIds": ["642e793dc46d098d64514607"]
    },
    {
        "orderLineItemIndex": 1,
        "productReference": "24299",
        "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
    }]
  }'

Post-processing results

When processing a project that includes many line items of an order, you may want to do some operations only when processing has been completed for all the line items. For example, if you need to send files to your system in a single request, only when all of them are rendered, or switch the status in your system at the end.

To do this, you can create a separate pipeline and configure it so that it runs at the end of the processing process for a project. Such a post-processing pipeline is global for a single integration.

For example, a post-processing pipeline may consist of only two tasks, send-email and finalize to send email notifications when rendering is completed.

{
    "tasks": [
        {
            "description": "Email notification",
            "name": "send-email",
            "type": "send-email",
            "parameters": {
                "recipients": "recipient@example.com",
                "subject": "Your print files are ready",
                "body": "You can download print files for your personalized designs here: <br> {{$docs}} <br>",
                "useHtmlBody": true,
                "$docs": "results for item {{project.items.$.name}}: {{$:result*}} <br>"
            },
            "outputArtifacts": []
        },
        {
            "description": "Finalize",
            "name": "finalize",
            "type": "finalize",
            "finalArtifacts": [
                "result*"
            ]
        }
    ]
}

You can create a post-processing pipeline in your Customer's Canvas account. To assign it to a single integration, navigate to Settings > Integrations, hover over the ellipsis in the integration row, click Edit, and select a pipeline in the Project post-processing pipeline drop-down list.

For more details, refer to the Integration Settings topic.

As you have already learned about rendering a specific pipeline, the endpoint /api/storefront/v1/projects/by-scenario/specific-pipeline allows you to create a project to process several products defined in the items array. This is how you can render the products from the previous example through the custom pipeline 247.

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "orderDetails": {"orderId": "1004"},
    "items": [{
        "orderLineItemIndex": 0,
        "designIds": ["642e793dc46d098d64514607"]
    },
    {
        "orderLineItemIndex": 1,
        "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
    }],
    "scenario": {"pipelineId": 247}
  }'

In scenario, you can also apply post-processing in the postProcessingPipelineId property. If you need to use different pipelines to process different products, you can assign the pipelines by product names in the itemPipelines array as follows:

• cURL
• HTTP
• C#
• TS
• PHP

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
    "ownerId": "6527afc635b52bfadd355226",
    "orderDetails": {"orderId": "1004"},
    "items": [{
        "name": "product1",
        "orderLineItemIndex": 0,
        "designIds": ["642e793dc46d098d64514607"]
    },
    {
        "name": "product2",
        "orderLineItemIndex": 1,
        "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
    }],
    "scenario": {
        "postProcessingPipelineId": 11,
        "itemPipelines": [
            { "itemName": "product1", "pipelineId": 247 },
            { "itemName": "product2", "pipelineId": 248 }
        ]
    }
  }'

Migration from legacy rendering methods

If you have integrated your system with Customer's Canvas earlier than 2023, you may find out that you are using deprecated methods of rendering. They include receiving a PDF link directly from Design Editor or by receiving a link through a deprecated endpoint of project.

In this section, you may learn how to migrate from legacy methods to the rendering service.

Let's assume you have obtained a description that contains a private design, and consider how to proceed in both cases.

Old Code

When you sent requests directly to the Design Editor as described in the API documentation, your code could look like this:

  var ccUrl = $"https://cc-apps.aurigma.net/design-editor/{version}";
  var apiUrl = $"{ccUrl}/api/hires/generateHires";

  var result = new List<string>();
  var model = new GetModel(userId, stateId);

  using (var client = new HttpClient())
  {
      var request = new HttpRequestMessage
      {
          Method = new HttpMethod("POST"),
          RequestUri = new Uri(apiUrl)
      };

      request.Headers.Add(ApiKeyHeaderName, deApiKey);
      request.Content = new StringContent(JsonSerializer.Serialize(model,, Encoding.UTF8, "application/json");

      var response = await client.SendAsync(request);
      var strResponse = await response.Content.ReadAsStringAsync();
      var responseModel = JsonSerializer.Deserialize<List<string>>(strResponse);

      if (responseModel[0] != null)
      {
          result.AddRange(responseModel[0]);
      }

      return result;
  };

Important

This method is no longer recommended and will be removed. Instead, render print files through the Personalization Platform.

In this code, you need to use stateId as the designId, and userId as ownerId in the project creation endpoint calls. For example, if you need the easiest way to render a design, you can create a project using the /api/storefront/v1/projects/by-scenario/render-hires endpoint as follows:

• cURL
• HTTP
• C#
• TS
• PHP

# First, send this request. 

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
       "ownerId": userId,
       "scenario": { "designId": stateId, "name": "print"}
      }'

# Then, poll the project's status to see if it is completed or failed.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/processing-results" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

Deprecated endpoints

If you integrated earlier than March 2023, you most likely created a project and received a URL from the project using the endpoints /api​/storefront​/v1​/projects​/{id}​/project-pdf or /api/storefront/v1/projects/{id}/project-pdf-zip, which returned a URL linking to or ZIP with a print file. For example,

curl -X \
GET "https://api.customerscanvashub.com/api/storefront/v1/projects/1/project-pdf?designUserId=&designId=" \
-H 'X-Api-Key: YOUR_TOKEN'

Important

This method is deprecated now and no longer recommended. Instead, we strongly advise using the processing pipelines.

Here, you can use the /api/storefront/v1/projects/by-scenario/render-hires endpoint and pass designUserId as ownerId together with designId in the request body, as described in the previous example.

If you received a zipped print file instead of a link to it, you can create a custom pipeline delivering a print file and then use the /api/storefront/v1/projects/by-scenario/specific-pipeline endpoint. For example, if the pipeline ID is 1234, then your calls may look as follows:

• cURL
• HTTP
• C#
• TS
• PHP

# First, send this request. 

curl -X \
POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H  "accept: text/plain" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer <TOKEN>" \
-d  '{
      "ownerId": designUserId,
      "items": [{
          "designIds": [designId]
      }],
      "scenario": {"pipelineId": 1234}
    }'

# Then, poll the project's status to see if it is completed or failed.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/processing-results" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"