Circle Functions

Circle functions provide access to campaign management features in XMPie Circle, enabling template instance management and touchpoint data retrieval. These functions allow you to create personalized URLs, differentiate between campaign instances, and access touchpoint-specific data for cross-media campaigns.

Instance ID

The Instance ID is accessed through the GetEnv function and provides a unique identifier to differentiate between instances created from the same template. When creating an instance from a template, the website is defined in the template and is shared by all its instances. The Instance ID allows each instance to be uniquely identified in URLs and other contexts.

This function returns a String data type.

Syntax

GetEnv("InstanceID")

This function takes no additional parameters beyond the constant name.

Usage in URLs

The Instance ID is commonly used in personalized URLs (PURLs) to ensure that each campaign instance can be tracked separately. When building URLs, you can incorporate the Instance ID using template placeholders.

URL Format Examples

Format

Example

Path-based

http://www.MyDomain.com/{{GetEnvInstanceID}}/{{XMPieRecipientKey}}

Query string-based

http://www.MyDomain.com/MyFolder/Landing.html?iid={{GetEnvInstanceID}}&rid={{XMPieRecipientKey}}

Examples

  1. Get the current instance ID:

    GetEnv("InstanceID")

    Result: "12345" (unique identifier for this campaign instance)

  2. Build a personalized landing page URL:

    "https://www.example.com/campaign/" & GetEnv("InstanceID") & "/" & |->[RecipientKey]

    If InstanceID = "ABC123" and RecipientKey = "R5678":

    Result: "https://www.example.com/campaign/ABC123/R5678"

  3. Create a tracking URL with instance and recipient identifiers:

    "https://track.example.com/click?instance=" & GetEnv("InstanceID") & "&recipient=" & |->[CustomerID]

  4. Build a QR code URL that includes instance tracking:

    GetEnv("BaseURL") & "/qr/" & GetEnv("InstanceID") & "/" & SecureID()

Note: The Instance ID is particularly important when running multiple campaigns from the same template. Each instance will have a unique ID, allowing analytics and responses to be attributed to the correct campaign instance.

GetTouchpointData function

The GetTouchpointData function retrieves specific data associated with designated touchpoints in a Circle campaign. Touchpoints represent the various channels and interactions in a cross-media campaign (e.g., web pages, print pieces, emails). This function allows you to access data from other touchpoints within your campaign.

This function returns a String data type containing the requested touchpoint data, or an empty value if the data is not available.

Syntax

GetTouchpointData(touchpointIdentifier, dataType)

Parameter

Description

touchpointIdentifier

Required. The friendly identifier of the touchpoint (e.g., "W1", "W2", "P5", "E1"). This identifier is assigned when the touchpoint is created in Circle.

dataType

Required. The type of data to retrieve from the touchpoint (e.g., "URL").

Touchpoint Identifier Naming Convention

Prefix

Touchpoint Type

Examples

W

Web touchpoint

W1, W2, W3

P

Print touchpoint

P1, P2, P5

E

Email touchpoint

E1, E2

Data Types

Data Type

Description

"URL"

The landing page URL for the touchpoint, personalized for the specific recipient and Circle project instance

Examples

  1. Get the URL for web touchpoint W1:

    GetTouchpointData("W1", "URL")

    Result: "https://www.example.com/campaign/landing/ABC123/R5678"

    Returns the landing page URL of web touchpoint W1 for the specific recipient and Circle project instance.

  2. Get the URL for a different web touchpoint:

    GetTouchpointData("W2", "URL")

    Result: The personalized URL for web touchpoint W2

  3. Include a web touchpoint URL in print materials:

    "Visit your personalized page at: " & GetTouchpointData("W1", "URL")

    Result: "Visit your personalized page at: https://www.example.com/campaign/ABC123/R5678"

  4. Create a shortened display URL while using the full tracking URL:

    "www.example.com/offer"

    The actual hyperlink would use:

    GetTouchpointData("W1", "URL")

  5. Reference a touchpoint URL in an email that links to a web landing page:

    "<a href=\"" & GetTouchpointData("W1", "URL") & "\">View Your Personalized Offer</a>"

  6. Conditional inclusion based on touchpoint availability:

    If (GetTouchpointData("W1", "URL") != "") {
    "Visit: " & GetTouchpointData("W1", "URL")
    } else {
    "Visit: www.example.com"
    }

Important: The GetTouchpointData function returns data only when production is run through Circle. If the job is not run via Circle, the function returns an empty value but production continues without failure. This allows templates to be used both within and outside of Circle campaigns.

Cross-Media Campaign Workflow

Circle functions are typically used in cross-media campaigns where multiple touchpoints work together:

  1. Print Touchpoint (P1): A direct mail piece containing a personalized URL generated using GetTouchpointData("W1", "URL")

  2. Web Touchpoint (W1): A personalized landing page that the recipient visits

  3. Email Touchpoint (E1): A follow-up email triggered by web activity, containing links to additional web touchpoints

By using GetTouchpointData, each touchpoint can reference and link to other touchpoints in the campaign, creating a cohesive cross-media experience with full tracking and attribution.

More topics