populate-psd-template

Last updated on August 26, 2025
•
5 minutes to read

This command is used to place an array of images on a large sheet according to the layout specified in the PSD template. The underlying rendering process supports advanced features such as applying vector masks to images. Due to the specifics of the rendering mechanism, it is not possible to manually set the DPI of the output file. The output DPI is derived from the PSD template itself.

Parameters

Defining a template

The template source can be specified in two ways:

Using two parameters:
- templateName (string): The name of the PSD file in the tenant's Image assets, which describes the template for the arrangement of images.
- templateFolder (string): The folder path containing the PSD template in the tenant's Image assets. The default is "/", which means the root folder.
Using the templateId (string) — the identifier of the PSD file in the Images asset section. If this parameter is specified, it overrides templateName and templateFolder.

Tip

You can parameterize the file name using the interpolation mechanism. For example, if your workflow populates a field in a project, such as TemplateName, you can refer to it using the following expression:

"templateName": "{{project.items.@.TemplateName}}"

Configuring the rendering

inputRepeatCount (integer): Specifies how many times the entire list of input images will be repeated. (A, B, C * 3 = A, B, C, A, B, C, A, B, C). The default value is 1.
inputImageDpi (integer): DPI of the input images. Required for correctly reading the PDF results of design rendering. The default value is 300.
inputImageResizeMode (string): Specifies how to modify the size of the input image if it does not match the size of the smart object. Possible values: Fit, Shrink, Resize, and ImageFill. The default value is Fit.
outputToSeparateFiles (boolean): If True, the pages of a multipage result will be rendered in separate files. Possible values: True and False. The default value is False.
outputFormat (string): The format of the rendered file. Possible values: Jpeg, Png, Tiff, and Pdf. The default format is Pdf.
outputPdfCompression (string): The method of compressing data within the rendered file, must match the output file format. Value and details.
outputJpegCompressionQuality (integer): The level of compression for the content within the rendered file. Applies to file formats PDF, JPEG, and TIFF. 100 corresponds to maximum quality and file size, while 0 corresponds to minimum quality and file size. The default quality is 90.
outputPngCompressionLevel (integer): The level of compression for the content within the rendered file. Applies to PNG format. -2 is the minimum value, 9 is the maximum. The default value is 2.
outputPdfAuthor (string): The "Author" property of metadata for the PDF format.
outputPdfCreator (string): The "Creator" property of metadata for the PDF format.
outputPdfKeywords (string): The "Keywords" property of metadata for the PDF format.
outputPdfSubject (string): The "Subject" property of metadata for the PDF format.
outputPdfTitle (string): The "Title" property of metadata for the PDF format.
outputArchiveType (string): If specified, the rendering result will be packed into an archive. Possible values: Zip and SevenZip. By default, it is not specified.
outputArchiveCompressionType (string): Supported types: None, Copy, Default, Deflate, Deflate64, Lzma, and Lzma2. The default type is Default.

Notes on archiving results:

If a single artifact (result) is expected as output, all generated files will be packed into one archive.
If a collection of artifacts (result*) is expected as output, each generated file will be packed into a separate archive.

Input

Images in PDF, JPEG, PNG, and TIFF formats can be submitted to the input. It can be a single image or a multi-page file, packed into an archive or not. The task will insert these images as is, preserving vector data and the color space.

When you have a single file or a multi-page file at the input, specify a single input artifact.

{
  "inputArtifacts": ["design"]
}

To provide many files to the input, list them separated by commas or add an asterisk to the artifact name.

{
  "inputArtifacts": ["design*"]
}

By default, the inputRepeatCount parameter is 1. This means that the task will insert input images into placeholders in a single copy, leaving the rest of the placeholders blank. If you have a single image at the input, it will populate all the placeholders.

For multiple input images, you need to control the number of these images and placeholders. For example, for two images and eight placeholders, set inputRepeatCount to 4.

{
    "parameters": {
        "inputRepeatCount": 4
    },
    "inputArtifacts": ["design-1", "design-2"]
}

Output

When you have a single image at the input, the task will create a single file with the populated template. In this case, specify a single output artifact.

{
  "outputArtifacts": ["result"]
}

If there are many file copies at the input or a multi-page PDF, and if images remain after filling in all placeholders, the task creates the next page and so on until all images are used.

At the same time, you have several options to configure the output files:

Set outputToSeparateFiles to false and get a single multi-page PDF.

{
    "parameters": {
        "outputToSeparateFiles": false
    },
    "outputArtifacts": ["result"]
}

Create several single-page files and pack them into a single archive.

{
    "parameters": {
        "outputToSeparateFiles": true,
        "outputArchiveType": "SevenZip",
        "outputArchiveCompressionType": "lzma"
    },
    "outputArtifacts": ["result"]
}

Send each page to a separate file and get many files at the output. If needed, they can also be archived, but a separate archive will be created for each file:

{
    "parameters": {
        "outputToSeparateFiles": true,
        "outputArchiveType": "SevenZip",
        "outputArchiveCompressionType": "lzma"
    },
    "outputArtifacts": ["result*"]
}

Example

{
  "description": "Populate PSD Template",
  "name": "populate-psd-template",
  "type": "populate-psd-template",
  "inputArtifacts": [
    "rendered"
  ],
  "parameters": {
    "templateName": "bc-8up-letter.psd",
    "templateFolder": "/PSD Templates",
    "inputImageDpi": 300,
    "inputRepeatCount": 4,
    "outputFormat": "pdf",
    "outputToSeparateFiles": true
  },
  "outputArtifacts": [
    "result*"
  ]
}