Argument interpolation

Last updated on December 29, 2023
•
4-5 minutes to read

In task parameters, you can use specific values such as 300, "pdf", or true. However, it's often insufficient to rely solely on such values, as you might need to reference project data or previously created artifacts. In such cases, argument interpolation comes into play, enabling you to replace arguments with their values.

Interpolation syntax looks as follows:

{{argument}}

Interpolating project data

Each pipeline has access to the description of the corresponding project. Therefore, each task can use project data as arguments for interpolation within parameters.

When referring to a project property, specify project.<property-name>, for example:

"Customer": "{{project.customerName}}"

You can also access nested properties through a dot.

For properties in an array, you can access their elements using dot notation with an index: project.items.<index>. However, using an explicitly specified index number is only useful when there is only one item in the project. In general, refer to an element using the marker of the current element @.

"Products": "{{project.items.@.name}}",
"Quantity": "{{project.items.@.quantity}}"

Note that the @ marker only applies to project elements. For other enumerations (designs, resources, etc.), the concept of the current element is not applicable.

In the following project model, you can find both the project properties and how arguments map to them.

project = {
    id,                     // project.id
    name,                   // project.name
    customerId,             // project.customerId
    customerName,           // project.customerName
    orderId,                // project.orderId
    orderNumber,            // project.orderNumber
    orderUrl,               // project.orderUrl
    orderLineItemId,        // project.orderLineItemId
    orderLineItemIndex,     // project.orderLineItemIndex
    templateId,             // project.templateId
    items = [{
        id,                 // project.items.@.id
        name,               // project.items.@.name
        quantity,           // project.items.@.quantity
        key,                // project.items.@.key
        fields = { [field-key:string]: string },    // project.items.@.fields
        hidden = { [hidden-key:string]: string },   // project.items.@.hidden
        sku,                // project.items.@.sku
        userId,             // project.items.@.userId
        stateId             // project.items.@.stateId
        designs = [{
            designId        // project.items.@.designs.0.designId
        }],
        resources = [{
            resourceId,     // project.items.@.resources.0.resourceId
            name            // project.items.@.resources.0.name
        }]
    }]
}

Missing values

If an argument is not found, the interpolation will not occur, and the task will terminate with an error. However, you can prevent this by replacing missing values with an empty value adding the symbol "?" to the argument. In such cases, {{argument?}} will be replaced with an empty string.

Interpolating artifact data

You can apply interpolation of previously produced artifacts to get their properties, such as ID or URL.

Assuming you've specified "inputArtifacts": ["design", "images*"], here's how you can apply the interpolation in the parameters.

To retrieve an ID from the corresponding artifact in asset storage, use:

"designId": "{{design}}"    // -> "6165234b2475c0a1239b90b9"

In this case, the task will terminate if no designs were specified in artifacts. To complete a task by using an empty string when a value is missing, add the symbol "?".

This symbol allows you to get an artifact ID in asset storage only if the artifact is listed in inputArtifacts and the corresponding file exists in the storage. Otherwise, it will pass an empty value.

"designId": "{{design?}}"    // -> "6165234b2475c0a1239b90b9" or ""

Now, let's get an artifact URL, for example, a design link.

"designLink": "{{design:url}}"    // -> "https://dm-assetstorage.azurewebsites.net/api/storage/v1/artifacts/6165234b2475c0ae699b90b9/file?tenantId=2"

In the same way, you can avoid missing values.

"designLink": "{{design:url?}}"    // -> "https://dm-assetstorage.azurewebsites.net/api/storage/v1/artifacts/6165234b2475c0ae699b90b9/file?tenantId=2" or ""

The resulting URL can be used to embed a link to a page. To provide a downloadable link, use the attachment-url interpolation. This is how you can provide the downloadable link to the first image from the images collection.

"preview": "{{images1:attachment-url}}"    // -> "https://dm-assetstorage.azurewebsites.net/api/storage/v1/artifacts/616751234475c0ae699b90b9/file?tenantId=2&attachment=true"

The link includes the attachment=true query parameter, indicating the file will be provided in the "attachment" mode and allowing users to download and save the file to disk.

For collections, you can retrieve a list of IDs as a single comma-separated string:

"previews": "{{images*}}"    // -> "65234b2475c0a1239b90b9, 8084234b2475c0a1239bac53"

This may not suit you if you need to insert the result into JSON. As an alternative, use the list-json param, which adds quotes to the IDs. Then, you can add other items to this list and enclose everything in square brackets.

"previews": "{{images*:list-json}}"    // -> "65234b2475c0a1239b90b9", "8084234b2475c0a1239bac53"

Each item of a project is processed using a separate job with its own set of artifacts. Sometimes you may need data from another job of the same project, for example, in a post-processing pipeline, you need to collect data from all the jobs in the project. You can apply interpolation of such related artifacts to get their properties.

When referring to related artifacts, specify {{<project-item-index>:<artifact-specifier>}}, for example:

"{{0:design}}", "{{0:design?}}", "{{0:design:url}}", "{{0:images*}}", and "{{0:images*:url}}" will be replaced with the corresponding data from the project item with the index 0.
"{{1:design}}", "{{1:design?}}", "{{1:design:url}}", "{{1:images*}}", "{{1:images*:url}}" will be replaced with the corresponding data from the project item with the index 1.
And so on for other indexes.

If the data involves a similar processing scenario, they can be grouped by names from different project items. To do this, use the marker * as a prefix: {{*:<artifact-specifier>}}.

To retrieve a list of single design IDs collected from different project items, use:

"designId": "{{*:design}}"    // -> "65234b2475c0ae699b90b9, 8084234b2475c0ae699bac53"

To get a list of artifact IDs from image* collections from different project items, use:

"previews": "{{*:images*}}"    // -> "65234b2475c0ae699b90b9, 8084234b2475c0ae699bac53"

To apply interpolation of artifacts from the current job, use the marker @ as a prefix: {{@:<artifact-specifier>}}. Note that using this marker gives the same result as already mentioned argument interpolation:

"{{@:design}}", "{{@:design?}}", and "{{@:design:url}}" result in the same strings as "{{design}}", "{{design?}}", and "{{design:url}}", correspondingly.
"{{@:images*}}" and "{{@:images*:url}}" result in the same strings as "{{images*}}" and "{{images*:url}}", correspondingly.

Argument interpolation

Interpolating project data

Missing values

Interpolating artifact data

Interpolating related artifact data

Was this page helpful?