Customizing workflows with project fields

  • Last updated on July 21, 2025
  • •
  • 6 minutes to read

Customer's Canvas manages order processing via projects that initiate rendering pipelines. In addition to conveying standard order parameters, these projects include fields for storing supplementary data and customizing workflows.

Fields help you parametrize and control the behavior of pipelines within projects. They let you create a single pipeline that can be used across different product types. Here are just two examples of how fields might be applied:

  • Configuring a pipeline to support both variable-data printing scenarios as well as fixed-content printing cases.
  • Printing a particular product type either on paper or on transparent film by enabling image flipping where necessary.

Understanding project fields

When setting up a new project, you define fields, which act as key-value pairs storing essential metadata about the project. These fields store metadata such as product type, editing scenario, whether Variable Data Printing (VDP) is required, etc.

After defining these fields, you can utilize them inside your pipeline in three distinct ways:

  • Conditional task execution: a mechanism of creating a pipeline where a single tasks will execute conditionally based on field values. For example, a task runs if there's an associated VDP field present, and skips otherwise. We define all possible tasks needed for order processing, including or excluding steps dynamically using the skipIf and skipIfNot task parameters. For more details, see the Skipping tasks by condition topic.

  • Direct application in task parameters: the values from the fields are directly inserted into task parameters. This enables flexible configuration. For example, operations like flips or rotations can be automatically applied when rendering high-resolution images, based on the value stored in corresponding fields. For an example, see the download-files task.

  • Forward data for post-processing: the values from fields are used to transmit additional details (such as order IDs) between systems, particularly when handling complex integrations involving external shipping or storage platforms beyond your primary e-commerce solution. For more details, see the invoke-url task.

Defining fields

Consider a practical example. Imagine you're working on a project to render the design identified by the ID '62da200abb25c5477797d9cb', using a predefined pipeline tailored specifically for the product '24297'. Suppose your pipeline supports modifying the print filename, adjusting the orientation, and applying trimming to the final rendered output — all enabled by utilizing project fields. Here's what the configuration model might look like:

{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "Name": "Campaign",
            "Orientation": "Vertical",
            "Trim": false
        }
    }
}

To create a project, call the endpoint /api/storefront/v1/projects/with-single-item and pass the model there.

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"],
        "fields": {
            "Name": "Campaign",
            "Orientation": "Vertical",
            "Trim": false
        }
    }
}'

Here, we have created a project for a single product configured to use its pipeline. If you need to create a project for processing multiple products, using special pipelines, or using a rendering scenario, refer to the Working with projects topic.

Using fields

Fields can be utilized within pipelines to control the flow and behavior of tasks. The pipeline preprocessing uses specific symbols and syntax to reference fields.

  • Symbols and Syntax: Use {{ }} to enclose field references.
  • Accessing Elements: Use indexes project.items.<index> to access specific elements in a project. If your project contains only one product, use index 0: (project.items.0.name). To iterate over multiple items in a multi-product project and access the current item in a task, use the @ marker (project.items.@.name).

If a field may or may not be defined, add the ? operator after the field's name. When this syntax is used (for example, {{field?}}), the template will substitute either the actual argument value if it exists, or an empty string if no value is available.

Configuring pipelines

After you have defined all possible tasks required for order processing, include or exclude steps dynamically. There are two parameters for controlling task execution depending on field values:

  • skipIf: Specifies conditions under which a task should be skipped. For instance, if a certain field has a specific value, the task won't run.
  • skipIfNot: Works inversely—specifies conditions under which a task must run. If the specified condition isn't met, the task gets skipped.

Note that logical operators such as AND (&&) and OR (||) are not directly supported. However, you can achieve similar logical outcomes by using both skipIf and skipIfNot parameters together within a single task. Each task can include up to one instance of each parameter.

For example, if you are configuring a pipeline that may trim the resulting print files, you can manage this through a field. Let's say, you have defined a Trim field in a project and its value is true. To check whether trimming is required, use the following condition in task parameters:

{
    "skipIf": "{{project.items.@.fields.Trim}} = false"
}

Add this parameter to the conditional task that controls whether cut lines should be applied to print files, combine-with-cut-pattern. If the Trim field is not false, this task will include cut lines in the print files; otherwise, this task will be skipped.

{
    "tasks": [
        ...
        {
            "description": "Apply cut lines",
            "type": "combine-with-cut-pattern",
            "inputArtifacts": [
                "rendering-result*"
            ],
            "parameters": {
                "skipIf": "{{project.items.@.fields.Trim}} = false",
                "cutPatternName": "cut-pattern-1.pdf",
                ...
            },
            "outputArtifacts": [
                "combined-result*"
            ]
        },
        ...
    ]
}

Defining task parameters

When you use project fields to define task parameters, for example, rendering settings, your task may look as follows:

{
    "description": "Prepare print file",
    "name": "rendering outputs",
    "type": "render-hires",
    "inputArtifacts": [
        "design"
    ],
    "parameters": {
        "hiResOutputDpi": 200,
        "hiResOutputFlipMode": "{{project.items.@.fields.Flip?}}",
        "hiResOutputRotateMode": "{{project.items.@.fields.Rotate?}}"
    },
    "outputArtifacts": [
        "result*"
    ]
}

If you skip adding the Flip and Rotate fields in the project, these parameters will take their default values.

Forward project data

Use the invoke-url task to provide data to your integration system. In this case, the data can be picked up in webhooks so that you could perform additional processing.

In the request payload, you can pass the data as follows:

{
    "description": "Register print files",
    "type": "invoke-url",
    "inputArtifacts": [
        "result*"
    ],
    "parameters": {
        "body": {
            "campaignProjectId": "{{project.id}}",
            "orderId": "{{project.orderId}}",
            "name": "{{project.items.@.fields.Name?}}",
            "orientation": "{{project.items.@.fields.Orientation?}}"
        }
    }
}

Next, let's learn how to download rendered print files.

Was this page helpful?
Back to top Copyright © 2001–2025 Aurigma, Inc. All rights reserved.