Asset Functions

Asset functions enable you to work with graphics, PDFs, and web content programmatically. These functions allow you to verify asset existence, retrieve file paths and URLs, count PDF pages, generate dynamic graphics, and download content from the web.

Media Type Values

Several asset functions accept a media type parameter to specify which type of asset to work with:

Value

Media Type

Description

3

Web Graphics

Graphics optimized for web output

6

Web Text

Text content for web output

7

Print Text

Text content for print output

8

Print Graphics

Graphics optimized for print output (default)

IsAssetExist function

The IsAssetExist function verifies whether an asset exists in the campaign's asset library. This is useful for conditional logic to handle missing assets gracefully or to select alternative content when an asset is not available.

This function returns a Boolean data type.

Syntax

IsAssetExist(assetIdAsString [, mediaTypeNumber])

Parameter

Description

assetIdAsString

Required. The asset identifier (filename or asset ID) to check for existence.

mediaTypeNumber

Optional. The media type to search (3=web graphics, 6=web text, 7=print text, 8=print graphics). Defaults to 8 (print graphics) if omitted.

Examples

  1. Check if a print graphic asset exists:

    IsAssetExist("logo.png")

    Result: True (if the asset exists)

  2. Check if a web graphic asset exists:

    IsAssetExist("banner.jpg", 3)

    Result: True or False

  3. Use conditional logic to handle missing assets:

    If(IsAssetExist(|->[ProductImage])) {|->[ProductImage]} else {"default_product.png"}

    Result: Returns the product image if it exists, otherwise returns a default image.

  4. Check for a recipient-specific asset:

    IsAssetExist(|->[CustomerID] & "_photo.jpg")

    If CustomerID = "C1001":

    Result: True (if "C1001_photo.jpg" exists), otherwise False.

GetAssetPath function

The GetAssetPath function retrieves the file system path for an asset. This is useful when you need the actual file location for processing or when working with external systems that require file paths.

This function returns a String data type (file path), or Null if the asset is not found.

Syntax

GetAssetPath(assetIdAsString [, mediaTypeNumber])

Parameter

Description

assetIdAsString

Required. The asset identifier (filename or asset ID) to retrieve the path for.

mediaTypeNumber

Optional. The media type to search (3=web graphics, 6=web text, 7=print text, 8=print graphics). Defaults to 8 (print graphics) if omitted.

Examples

  1. Get the path for a print graphic asset:

    GetAssetPath("product_photo.jpg")

    Result: "C:\XMPie\Assets\Campaign123\product_photo.jpg"

  2. Get the path for a web graphic asset:

    GetAssetPath("hero_banner.png", 3)

    Result: Path to the web graphics version of the asset

  3. Build a dynamic asset path based on recipient data:

    GetAssetPath(|->[Region] & "_map.pdf")

    If Region = "Northeast":

    Result: Path to "Northeast_map.pdf"

  4. Handle missing assets with a fallback:

    If(GetAssetPath(|->[CustomLogo]) != Null) {
    GetAssetPath(|->[CustomLogo])
    } else {
    GetAssetPath("default_logo.png")
    }

Note: The returned path is the server-side file system path. This is typically used for internal processing and may not be accessible from external systems.

GetAssetWebURL function

The GetAssetWebURL function obtains a web-accessible URL for an asset. This is useful when you need to reference assets in HTML emails, web pages, or any context where a URL is required instead of a file path.

This function returns a String data type (URL), or Null if the asset is not found.

Syntax

GetAssetWebURL(assetIdAsString [, mediaTypeNumber])

Parameter

Description

assetIdAsString

Required. The asset identifier (filename or asset ID) to retrieve the URL for.

mediaTypeNumber

Optional. The media type to search (3=web graphics, 6=web text, 7=print text, 8=print graphics). Defaults to 8 (print graphics) if omitted.

Examples

  1. Get the web URL for an asset:

    GetAssetWebURL("Pic1.pdf")

    Result: "https://www.example.com/assets/Pic1.pdf"

  2. Get the URL for a web graphic:

    GetAssetWebURL("email_header.png", 3)

    Result: URL to the web-optimized version

  3. Build an HTML image tag with asset URL:

    "<img src=\"" & GetAssetWebURL(|->[ProductImage], 3) & "\" alt=\"Product\">"

    If ProductImage = "widget.jpg":

    Result: "<img src="https://example.com/assets/widget.jpg" alt="Product">"

  4. Create a download link for a PDF:

    "<a href=\"" & GetAssetWebURL(|->[BrochureFile]) & "\">Download Brochure</a>"

  5. Get asset URL with a fallback if it doesn't exist:

    If(GetAssetWebURL(|->[PersonalizedImage], 3) != Null) {
    GetAssetWebURL(|->[PersonalizedImage], 3)
    } else {
    GetAssetWebURL("generic_image.jpg", 3)
    }

GetPDFAssetPageCount function

The GetPDFAssetPageCount function counts the number of pages in a PDF document asset. This is useful for dynamic document assembly, pagination logic, or validating PDF assets before use.

This function returns a Number data type (integer page count). Returns 0 if the asset is not found or is not a valid PDF.

Syntax

GetPDFAssetPageCount(assetIdAsString)

Parameter

Description

assetIdAsString

Required. The asset identifier (filename or asset ID) of the PDF document.

Examples

  1. Get the page count of a PDF:

    GetPDFAssetPageCount("catalog.pdf")

    If catalog.pdf exists, is a valid PDF and has 24 pages:

    Result: 24

  2. Get page count for a recipient-specific document:

    GetPDFAssetPageCount(|->[ContractFile])

    If ContractFile = "contract_v2.pdf" (a 5-page document):

    Result: 5

  3. Conditionally process based on page count:

    If(GetPDFAssetPageCount(|->[InsertPDF]) > 10) {
    "Large document - additional postage required"
    } else {
    "Standard postage"
    }

  4. Validate PDF before including:

    If(GetPDFAssetPageCount(|->[Attachment]) > 0) {
    "Valid PDF attached"
    } else {
    "No valid PDF found"
    }

  5. Calculate total pages across multiple PDFs:

    GetPDFAssetPageCount(|->[Doc1]) + GetPDFAssetPageCount(|->[Doc2]) + GetPDFAssetPageCount(|->[Doc3])

Rectangle function

The Rectangle function generates a dynamic rectangular graphic with a specified CMYK color. This allows you to create colored rectangles on-the-fly based on data, useful for dynamic color selection in personalized products, color swatches, or background elements.

This function returns a Graphic asset that can be used in graphic ADORs.

Syntax

Rectangle(cyanPercentage, magentaPercentage, yellowPercentage, blackPercentage)

Parameter

Description

cyanPercentage

Required. The cyan component (0-100).

magentaPercentage

Required. The magenta component (0-100).

yellowPercentage

Required. The yellow component (0-100).

blackPercentage

Required. The black (key) component (0-100).

Common CMYK Color Values

Color

C

M

Y

K

Black

0

0

0

100

White

0

0

0

0

Red

0

100

100

0

Green

100

0

100

0

Blue

100

100

0

0

Yellow

0

0

100

0

Cyan

100

0

0

0

Magenta

0

100

0

0

Examples

  1. Create a solid black rectangle:

    Rectangle(0, 0, 0, 100)

    Result: A black rectangular graphic

  2. Create a red rectangle:

    Rectangle(0, 100, 100, 0)

    Result: A red rectangular graphic

  3. Create a dynamic color based on recipient data:

    Rectangle(|->[CyanValue], |->[MagentaValue], |->[YellowValue], |->[BlackValue])

    If CyanValue=50, MagentaValue=25, YellowValue=0, BlackValue=10:

    Result: A custom-colored rectangle based on recipient preferences

  4. Create a color swatch for a product:

    Switch(|->[ProductColor])
    {
    case "Red":
    Rectangle(0, 100, 100, 0)
    case "Blue":
    Rectangle(100, 100, 0, 0)
    case "Green":
    Rectangle(100, 0, 100, 0)
    default:
    Rectangle(0, 0, 0, 50)
    }

    Result: Returns a colored rectangle based on the product color selection.

Note: The Rectangle function generates a graphic asset dynamically at composition time. The size of the rectangle is determined by the graphic frame in your document template.

Tip: Click here to learn how to create a dynamic color picker in uStore using the Rectangle function.

Web.URLContentAsFile function

The Web.URLContentAsFile function downloads content from a URL and makes it available as an asset. This is useful for incorporating dynamic web content, fetching images from external servers, or integrating with web services that provide image content.

This function returns a Graphic asset (the downloaded content), or a default asset if the download fails.

Syntax

Call Web.URLContentAsFile(URL [, timeout, defaultAssetName, contentType])

Parameter

Description

URL

Required. The web URL to download content from.

timeout

Optional. Maximum time in seconds to wait for the download. Defaults to 30 seconds.

defaultAssetName

Optional. The name of a fallback asset to use if the download fails.

contentType

Optional. The expected IANA MIME type of the content (e.g., "image/jpeg", "image/png").

Examples

  1. Download an image from a URL:

    Call Web.URLContentAsFile("https://example.com/images/photo.jpg")

    Result: Photo.jpg is downloaded and used as an asset

  2. Download with a timeout and fallback:

    Call Web.URLContentAsFile("https://api.example.com/avatar/" & |->[UserID], 15, "default_avatar.png")

    Downloads the user's avatar with a 15-second timeout, falling back to default_avatar.png if it fails.

  3. Download with specific content type:

    Call Web.URLContentAsFile(|->[ImageURL], 30, "placeholder.jpg", "image/jpeg")

  4. Fetch a dynamically generated chart:

    Call Web.URLContentAsFile(
    "https://charts.example.com/generate?data=" & |->[SalesData] & "&type=bar",
    45,
    "chart_unavailable.png",
    "image/png"
    )

  5. Download a personalized map image:

    Call Web.URLContentAsFile(
    "https://maps.example.com/static?address=" & HtmlEncode(|->[Address]),
    20,
    "generic_map.png"
    )

Important: This function makes an HTTP request during composition. Ensure the target URL is accessible from the production server and consider timeout values for reliable job processing. Using a fallback asset is recommended to handle network failures gracefully.

Training: A video tutorial is available to show how to use the Web.URLContentAsFile() function.

PDFAssetPagesTable function

The PDFAssetPagesTable function generates table rows from the pages of a PDF document, with one row per page. This is useful for creating dynamic tables that display or reference individual PDF pages, such as document previews or page-by-page processing.

This function returns a Table data type with one row per PDF page.

Syntax

PDFAssetPagesTable(assetIdAsString)

Parameter

Description

assetIdAsString

Required. The asset identifier (filename or asset ID) of the PDF document.

Output Format

Each row in the returned table contains a reference to a single PDF page using the naming convention:

filename.pdf:pageNumber

Where pageNumber is 1-based (first page is 1, not 0).

Examples

  1. Generate a table from a PDF's pages:

    PDFAssetPagesTable("catalog.pdf")

    If catalog.pdf has 3 pages:

    Result: Table with rows "catalog.pdf:1", "catalog.pdf:2", "catalog.pdf:3"

  2. Create a thumbnail gallery of PDF pages in a table ADOR:

    PDFAssetPagesTable(|->[BrochureFile])

    Result: Use this in a Table ADOR with a graphic column to display each page as a thumbnail.

Usage Context: This function is typically used in Table ADOR expressions where the graphic column can reference individual PDF pages. The page reference format (filename.pdf:pageNumber) is understood by the composition engine when placing PDF pages as graphics.

Training: A video tutorial is available to show how to use the PDFAssetPagesTable() function to insert pages from a PDF asset into a dynamic document.

More topics