Message Templates

If you would like to join the early access program for XM Solution Plugins, then please let us know by taking this survey.

Not generally available

This feature is in Early Access and is not yet generally available. Functionality, APIs, and documentation may change before general availability.

XM Solutions support two message template resource types:

• EX Project Message Templates (exprojectmessagetemplates.v1) — a set of participant messages attached to an EX Project.
• Library Message (librarymessage.v0) — a single message stored in a Qualtrics message library, usable in surveys, email tasks, and other distribution flows.

EX Project Message Templates

What is the EX Project Message Templates resource?

The EX Project Message Templates resource contains a set of messages that can be sent to participants of this EX Project.

info

You can have at most 1 EX Project Message Templates resource per EX Project.

Any and all messages associated with that EX Project are consolidated into one resource.

Context

The EX Project Message Templates resource will generate one field:

• exProjectId

The exProjectId will be the id of your EX Project and can be accessed with <step.id>.exProjectId.

How to import an EX Project Message Templates resource into an XM Solution

Using the XM Solution CLI

You can import an EX Project Message Templates resource along with its associated EX Project resources using the CLI import command.

To do this, follow these directions to import an EX Project.

Now you should have your EX Project and all of its dependencies downloaded into a src/Resources_**** folder of your solution plugin. This will include an EX Project Message Templates resource if the EX Project has any messages.

Solution Execution

EX Project Message Templates resources are created using a "Create" step or updated using an "Update" step in the Solution Execution file.

{
  "id": "Messages",
  "type": "Create",
  "dependencies": [
    "EXProject"
  ],
  "config": {
    "apiVersion": "exprojectmessagetemplates.v1",
    "templateFilePath": "Resources/Messages.json",
    "transformationFilePath": "Resources/interpolate.js"
  }
}

The current apiVersion for EX Project Message Templates resources is "exprojectmessagetemplates.v1".

Common / Required changes

EX Project Message Templates resources will need their exProjectId field replaced with "{{ $.EXProjectStep.id }}" where EXProjectStep is the id of the EX Project step that this EX Project Message Templates resource depends on.

Library Message

What is the Library Message resource?

The Library Message resource (librarymessage.v0) creates a single message in a Qualtrics message library. Library messages can be used in surveys, email tasks, and other distribution flows within the platform.

Context

The Library Message resource will generate three fields:

• elementId
• id
• libraryId

The elementId and id will be your Library Message's id (MS_*****), which can be used in further resources that accept a library message (surveys, email tasks, etc.). The libraryId will be the library's id, which is typically the installing user's id (UR_*****).

How to create a Library Message resource

There is no CLI import for Library Message resources. Create a JSON file in your Resources_* folder with the following structure:

{
    "elementName": "New Message ({{$.setup.answers.title}})",
    "messageType": "MIE",
    "libraryID": "{{$.user.userId}}",
    "payload": {
        "EN": "<strong>Content of Message</strong>",
        "FR": "<em>Content of Message (Francois)</em>"
    }
}

The elementName, messageType, and payload fields are required.

info

If no libraryID is provided, the installing user's userId is used automatically. You can also hardcode a specific library ID here, but using {{$.user.userId}} is the recommended approach so the message lands in the correct user's library at install time.

You can also use the generate_library_messages.py script to pull existing messages from a Qualtrics library and generate resource files automatically.

messageType

The messageType field determines the sub-type of the message, which controls where it can be shown and used in the platform. Use the table below to find the correct code for the type of message you want to create.

Code	Full Name
MIE	InviteEmails
MIS	InactiveSurveyMessages
MRE	ReminderEmails
MTE	ThankYouEmails
MTM	EndOfSurveyMessages
MGE	GeneralMessages
MVD	ValidationMessages
MLF	LookAndFeelMessages
MES	EmailSubject
MSM	SMSInvite
MTK	TicketMessages
MSR	SMSReminder
MST	SMSThankYou

Translations

Library Message resources support multiple languages in the payload field. Each key is a Qualtrics-standard language code ("EN" for American English, "FR" for non-Canadian French, etc.) and the value is the message content for that language.

HTML formatting

The content of a Library Message can use HTML formatting. If your HTML contains quotation marks, escape them with a backslash:

"EN": "Please visit this link: <a href=\"www.linktosomething\">Click \"me\"</a>"

Solution Execution

Library Message resources are created using a "Create" step or updated using an "Update" step in the Solution Execution file.

{
  "id": "libraryMessage",
  "type": "Create",
  "config": {
    "apiVersion": "librarymessage.v0",
    "templateFilePath": "Resources/libraryMessage.json",
    "transformationFilePath": "Resources/interpolate.js"
  }
}

{
  "id": "libraryMessage",
  "type": "Update",
  "config": {
    "apiVersion": "librarymessage.v0",
    "templateFilePath": "Resources/libraryMessage.json",
    "transformationFilePath": "Resources/interpolate.js"
  }
}

The current apiVersion for Library Message resources is "librarymessage.v0".

If you are setting values such as elementName or libraryID from setup answers or user context, make sure to include a transformation file. The standard interpolate.js boilerplate handles {{ $.path.to.value }} token replacement at create/update time.