Task structure

• Last updated on December 29, 2023
• •
• 2-3 minutes to read

A task is a single operation within a pipeline. It involves configuration parameters, input artifacts, and project data to produce output artifacts.

Tasks are represented in a JSON format as follows:

{
    "description": "Render brochure",
    "name": "render-brochure",
    "type": "render-hires",
    "inputArtifacts": [ ... ],
    "parameters": { ... },
    "outputArtifacts": [ ... ]
}

Task description

The following fields are used to distinguish tasks within a pipeline:

• type defines the specific function performed by the task, such as extracting a design, rendering print files, or sending a notification. For more details about task types, see the task reference.
• name is a unique identifier for the task within a pipeline.
• description is a label for the task that appears in Customer's Canvas BackOffice.

Input and output

The following fields define the input and output files that the task works with:

• inputArtifacts - a list of incoming artifacts for a task.
• outputArtifacts - a list of outgoing artifacts for a task.

Every element in these fields can be a single artifact or an artifact collection. The collection is a number of artifacts with the same name and a different identifier, which is specified by an asterisk * as the last character of the name. For example, page* stands for artifacts page1, page2, page3, and so on.

"inputArtifacts": [
    "template",
    "page*"
]

For more details, refer to the Artifacts topic.

Parameters

The parameters configure the tasks and determine how they will work. For example, you can define the output DPI, the file format, and whether the pages should be output to separate files for the render-hires task. To do so, you can use the hiResOutputDpi, hiResOutputFileFormat, and hiResOutputToSeparateFiles parameters as follows:

"parameters": {
    "hiResOutputDpi": 300,
    "hiResOutputFileFormat": "pdf",
    "hiResOutputToSeparateFiles": true
}

Note that some tasks do not require any parameters.

In the previous example, we use certain values such as 300, "pdf", or true. However, you can also apply interpolation to refer to some project data or previously created artifacts. The project data and artifacts use different syntax.

The syntax of the parameter interpolation is as follows:

{{field}}

For example, to get the such product data as SKU, use it like this:

"parameters": {
    "sku": "{{project.items.@.sku}}",
    ...
}

This syntax is also used for the artifact interpolation. This way, you can get a URL or ID from artifacts, a single value, or a collection. For example, if you define artifacts as "inputArtifacts" : [ "design", "images*" ], then you can interpolate the design identifier into parameters as follows:

"parameters": {
    "template" : "{{design}}",
    ...
}

For more details, refer to the Argument interpolation topic.

Example

A single task may look as follows:

{
    "description": "Render brochure",
    "name": "render-brochure",
    "type": "render-hires",
    "inputArtifacts": [
        "design"
    ],
    "parameters": {
        "hiResOutputDpi": 300,
        "hiResOutputFileFormat": "pdf",
        "hiResOutputToSeparateFiles": true
    },
    "outputArtifacts": [
        "result*"
    ]
}

Here, we render print files of a brochure by using the render-hires task. This task takes an input design file, renders a PDF at 300 DPI, and outputs individual pages of this design as separate files result1, result2, result3, and so on.

---

Now, let's explore how you can work with Artifacts.