Argument interpolation

• Last updated on December 29, 2023
• •
• 3 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}}"

For properties in an array, access their elements using dot notation with an index:

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

You can also access nested properties through a dot.

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.0.id
        name,               // project.items.0.name
        quantity,           // project.items.0.quantity
        key,                // project.items.0.key
        fields,             // project.items.0.fields
        hidden,             // project.items.0.hidden
        sku,                // project.items.0.sku
        userId,             // project.items.0.userId
        stateId             // project.items.0.stateId
    }]
}

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"