Using the Domo Campaigns Markup Language
Intro
There are many advanced features of this app that allow for even greater customization of your email campaigns. You can utilize the Domo Campaigns Markup Language to not only add more Domo content such as summary numbers or titles, but you can also specify the size of a card or limit the number of rows in a table.
When adding a distribution list to a campaign, you must specify columns that can act as filters. The filters are used as personalized data permissions (PDP) within the app. You can always make sure that recipients of your campaign are only seeing the data that is filtered to them.
Customizing Domo content
Although you can already insert cards and card titles natively in the app, you can also add content by using the Domo Campaign Markup Language. To add dynamic content from a card in Domo, simply add the following text to your email or attachment body:
{{domo-content-[card id]-[content type]}}
-
Replace [card id] with the ID of the card you wish to pull from.
-
Replace [content type] with the part of the card you want to reference.
Note: Valid content types include title, summarynumber, and description.
Example 1
You want to insert the title from card 1234567, so you would insert the text below in your email or attachment body:
{{domo-content-1234567-title}}
Example 2
Now, you want to insert the summary number from card 8868777. You would insert the following text:
{{domo-content-8868777-summarynumber}}
Changing Width, Height, or Scale
You can apply specific customizations to your Domo content such as width, height, or scale. simply add the following text to your email or attachment body:
{{domo-content-[card id]-chart width=[width] height=[height] scale=[scale]}}
-
Replace [card id] with the ID of the card you wish to pull from.
-
[width] and [height] specify the size of the image you want to insert into your template.
-
[Scale] is optional and always defaults to 1.0 if it is not set. This allows you to insert more detailed information in a smaller space as if you've zoomed the chart out.
Different Scales
All of the charts below are rendered at 300 width x 400 height but at different scales. At higher scales, you get more detailed content in the same size image.
1.0 1.5 2.0
Example 1
To insert the chart from card 8868777 and render in 800 width x 600 height, add the following text:
{{domo-content-8868777-chart width=800 height=600}}
Example 2
If you wanted to insert the same card as the example above but with a scale of 2.0, add the following text:
{{domo-content-8868777-chart width=800 height=600 scale=2.0}}
Table Cards
To add table cards, simply add the following text to your email or attachment body:
{{domo-content-[card id]-table width=[width] height=[height] scale=[scale] max-pages=[maximum number of pages] max-rows=[maximum number of rows]}}
-
Replace [card id] with the ID of the table card you wish to pull from.
-
[width] and [height] specifies the size of the image you want to insert into your template.
-
[Scale] is optional and always defaults to 1.0.
-
[maximum number of pages] and [maximum number of rows] are optional. Use these options to define a maximum number of pages or rows you want to include.
Example 1
If you want to include up to 5 pages of data, simply set your [maximum number of pages] attribute to 5, like so:
{{domo-content-8868777-chart width=800 height=600 scale=2.0 max-pages=5 max-rows=0}}
Example 2
If you want to include up to 100 rows of data, no matter how many pages that will take, simply set the [maximum number of rows] attribute to 100 and [maximum number of pages] to 0:
{{domo-content-8868777-chart width=800 height=600 scale=2.0 max-pages=0 max-rows=100}}
Distribution List Content
The Domo Campaigns Markup Language (DCML) can also be used to insert fields from the distribution list into campaign emails or attachments. If you want to add a field, simply add the following text to your email or attachment body:
{{domo-distribution-[field name]}}
-
Replace [field name] with the name of the column in the distribution list you wish to pull from.
Example 1
For example, if I wanted to insert the Name field from your distribution list, you would use the text below:
{{domo-distribution-name}}
Commenting out References
If you are having problems with a reference or want to comment it out for any reason, you can simply add an exclamation point (!) at the beginning of the text.
{{!domo-distribution-name}}
If a reference has been commented out, it will simply be removed when rendering the HTML or pdf.
Data Filters
Filters are used to send a subset of your data to a given recipient by creating custom filters as columns within your distribution list. You must have at least a single filter column but can have multiple filters that will be executed together when rendering your Domo content. Each filter is made up of 3 separate pieces: the column name, the operand, and the value. They are all assembled to create a single filter value, like so:
State is equal to Washington
Dataset Column Name
The column name specifies the column to which the filter is applied. Values entered here need to match the column names in the DataSet that is powering the cards referenced in your campaign.
Example 1
Order Date is greater than or equal to 01/01/2018 00:00:00
Example 2
Or you could only include the sales data for Washington:
Name is equal to John Smith
Multiple DataSets
If you are referencing multiple cards in your campaign that are powered by multiple datasets, then you MUST specify which dataset the filter applies to by providing the dataset id and the column name in this format:
[dataset id].[column]
Example 1
Add a filter to only include sales data for orders placed this year would look like this:
4bded6af-0556-4f24-b943-1858b6e84880.Order Date is greater than or equal to 01/01/2018 00:00:00
Operands
There are 11 different operands that can be used to create your filter:
-
Is equal to
-
Does not equal
-
Is greater than
-
Is greater than or equal to
-
Is less than
-
Is less than or equal to
-
Is between
-
Is in
-
Is not in
-
Is null
-
Is not null
Value
There are two different types of values that can be specified in the filter, a normal value and a column reference.
Normal Value
A normal value is considered an actual value in a column to be filtered on. For example, if you want to add a filter where the State column is equal to CA, you simply add CA as the value.
State is equal to CA
Column Reference
A column reference will take the value from any column in your distribution list and add that value to your filter. So if you want to filter by state and you already have state defined in your distribution list, you can just reference the column by surrounding the column name with %.
Example 1
If the first row of your distribution list contains information for John Doe and his state is CA, the filter will be set to State is equal to CA. If the second row of your distribution list contains information for Jane Doe and her state is UT, the filter will be set to State is equal to UT, and so forth.
State is equal to %State%
Wildcard Filter
If you don't want to specify any filters and wish to send unfiltered data and information in your email campaign, you must still define one filter column with the "wildcard" value of * in it. This will tell campaigns that you understand that the data and information being delivered is unfiltered.
Multiple DataSets with a Wildcard Filter
If you are referencing multiple cards in your campaign that are powered by multiple datasets, then you MUST specify which dataset the wildcard filter applies to by providing the DataSet ID in this format:
[dataset id]=*
Example 1
If you are referencing multiple datasets and want to specify this dataset as a wildcard, your filter column would look like this:
4bded6af-0556-4f24-b943-1858b6e84880=*
Multiple Filters
If you are creating and selecting multiple filter columns, the filter will be ANDed together. If you need to perform more complex filtering on your distribution list, you can use standard Domo tools like Magic ETL or Data Flows.
Using HTML to Format PDF Attachments
You can also utilize HTML to format PDF attachments. You can define the page size, orientation, and custom page breaks when the PDF is rendered.
Page size and orientation
DCML supports the @page annotation as documented in the CSS# Paged Media module. This allows you to easily specify the size of a page as well as the orientation by simply including some CSS in your HTML definition. For example, to render the PDF attachment in standard letter size (8.5" x 11") in a landscape orientation, you would include the following code to your HTML header:
<html>
<head>
<style type="text/css">
@page { size: letter landscape; }
</style>
</head>
<body>
...
You can also specify any custom size in the @page annotation. For example, if you want to render the PDF in 5" x 7", you would add the following code to your HTML header:
<html>
<head>
<style type="text/css">
@page { size: 5in 7in; }
</style>
</head>
<body>
...
The CSS3 definition also supports more sophisticated and extensive formatting which is also supported by DCML. You can find more details in the CSS3 specification.
Page Breaks
In order for page break annotations to work, the @media all and @media print properties must be defined somewhere in your CSS. If you don't have a defined CSS, simply include the following code in your HTML header:
<html>
<head>
<style type="text/css">
@media all {
.page-break { display: none; }
}
@media print {
.page-break { display: block; page-break-before: always; }
}
</style>
</head>
<body>
...
To add a manual page break to any document, you can simply add the following code to your HTML:
<div class="page-break"></div>
HTML Tags Not Rendering
If you have a title or summary number that contain HTML formatting, the HTML will not always render correctly in the pdf attachment. This is due to the encoding required to convert HTML to a pdf. In order to fix this issue, add the following flag to your DCML tag:
encoding=false
For example,
{{domo-content-8868777-summarynumber encoding=false}}
This stops Domo content from being encoded and will allow the HTML formatting to be rendered correctly.