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.0.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.