This is a small walkthrough of how to send emails with Digizuite Automation Workflows. In this walkthrough we will setup an email template that accepts a list of assets, and outputs the following:
The asset’s id
The asset’s title
A link to the asset with a thumbnail inside
The current status of the asset
Additionally we will setup an automation workflow to load a set of assets, and then send of an email.
As a precondition to following the walkthrough, it is expected that the reader has a basic understanding of the following concepts:
HTML
Emails
Basic programming and control structures
Preparing the mail template
The first thing we will take a look at is the email template. We start out with a pretty simply template that doesn’t do a whole lot, but let us go over how it works either way.
{{include 'html-header-start'}}
<title>Here is what happened since last time!</title>
{{include 'html-header-end'}}
<span class="preheader">Here is what happened since last time!</span>
<h1>Hi {{receiver.name | html.escape}},</h1>
<p>Here is what was uploaded since yesterday </p>
On line 1 you will notice the double curly braces {{, these denote that some special code should be run, and that it is not just html that to be printed directly into the final mail. In this case we are using a special scriban structure called an include. Specifically we are including another mail template here. This allows us to standadize somewhat how mails looks, and allows us to avoid having to repeat outselves. On line 3 we just output a title for the mail client to display. On line 5 we include another template. Next on line 7 we have the preheader, which is displayed by some email clients as the first part of the body, before you open the email. The preheader is not displayed in the actual mail. On line 9 we say hello to the receiver of the email. There are certain parts that are always loaded by the mail system. Specifically the receiver and sender. Important to notice is also that we use a pipe operator to call the html.escape function, to prevent html injection. Whenever you output data you don’t control, always remember to run it through html.escape. On line 10 we just output yet more text for the user to see.
Displaying a simple table
Next we need to start outputting out assets. As this is just a simple walkthrough, we will not focus on styling the email, and will just output the assets in a simple table.
First thing to do is setup the basic table structure:
<table>
<thread>
<tr>
<th>AssetId</th>
<th>Asset title</th>
<th>Thumbnail</th>
<th>Status</th>
</tr>
</thread>
<tbody>
...
</tbody>
</table>
If you have working with html before, there really shouldn’t be anything surpricing about this structure. We simply create a table with 4 rows, AssetId, Asset title, Thumbnail and Status. The rest is just basic layout for us to put out main output in.
Looping through our assets
Then we get to the interesting parts, we need to actually output some data. To do this we insert a for loop:
<tbody>
{{for assetId in data.assetIds}}
<tr>
...
</tr>
{{end}}
</tbody>
This will run once for every assetId in data.assetIds. How does data get into data.assetIds, you ask? This is handled by automation workflows, which we will get to later in this walkthrough. For now, lets continue looking at how we can output data.
Showing the asset id
First thing we wanted to display was the asset id. We already have the asset id available from the loop, so we can output it directly:
<tbody>
{{for assetId in data.assetIds}}
<tr>
<td>
{{assetId}}
</td>
...
</tr>
{{end}}
</tbody>
As seen on line 5, all we need to do is to write {{assetId}}.
Showing the asset title
Next we want to output the title of the asset. As can be seen in the auto-generated documentation below the mail template editor, there is a function called get_title, that takes an asset id, and returns string. Calling it is as simple as this:
<tbody>
{{for assetId in data.assetIds}}
<tr>
...
<td>
{{digizuite.get_title(assetId) | html.escape}}
</td>
...
</tr>
{{end}}
</tbody>
All the custom functions Digizuite makes available can be found on the digizuite object in the template. So in this case to call the function and get the title is as simple as {{digizuite.get_title(assetId)}}, and we simply pass the asset id as an argument to the function. As this is user provided input, we have to remember to escape it using html.escape, as mentioned earlier.
Showing a thumbnail of the asset
Next we want to display a thumbnail of the asset. To do this we have a function get_asset_thumbnail_url, which again takes an asset id. So we simply need to do this:
<tbody>
{{for assetId in data.assetIds}}
<tr>
...
<td>
<img src="{{digizuite.get_asset_thumbnail_url(assetId)}}" />
</td>
...
</tr>
{{end}}
</tbody>
And we will get a nice small thumbnail. Notice how we don’t need to escape anything here. The function already returns a well formed url, so it won’t cause any issues being included in the html like this.
Adding a link to the thumbnail
Next we want to thumbnail to actually take us to that asset in the Media Manager. For this we have a convenience function get_link_to_asset_preview, which takes a baseUrl to the Media Manager and an asset id. Because we want to entire image to be clickable, we wrap the entire thumbnail in an a tag with a link to the image:
<tbody>
{{for assetId in data.assetIds}}
<tr>
...
<td>
<a href="{{digizuite.get_link_to_asset_preview("https://mm.digizuite.com", assetId)}}">
<img src="{{digizuite.get_asset_thumbnail_url(assetId)}}" />
</a>
</td>
...
</tr>
{{end}}
</tbody>
If you have multiple Media Managers installed, you need to enter the link to the correct portal. You can use the config version id of the template to control this. Notice also that we again don’t need extra escaping, since this is again a well formed url already.
Displaying the asset status
As the last thing in the template we want to include the status of the asset. To do this we need to load the value of a metadata field. During this part we will also see how to do some even more advanced logic to conditionally display output in the template. The Status field is a combo metafield, so we need to use the get_combo_meta_field_value function. And as can be seen from the documentation, this function takes an assetId, which we already have available from the loop, and a metaFieldLabelId. This is the label id of the metafield, which also means it is language specific. On my system the labelId for the status field in english is 51550, so we will use that as an example. On your system it is likely to be different. Last thing we will notice about the function is that it returns a ComboValue, not a string like the other functions we used above. That means we have to extract a specific property from the ComboValue and display that. Additionally we want to handle the asset not having a status at all (Usually you have an automation workflow ensuring the asset always have a status, but for the sake of example, we will take a look at how to check)
<tbody>
{{for assetId in data.assetIds}}
<tr>
...
<td>
{{status = digizuite.get_combo_meta_field_value(assetId, 51550)}}
{{if status == null}}
Asset has no status
{{else}}
{{status.label | html.escape}}
{{end}}
</td>
</tr>
{{end}}
</tbody>
On line 6 you can see us calling the get_combo_meta_field_value function, passing in the assetId from the loop, and the labelId of the status metafield, and saving the result in the status variable. Next we wanted to handle the case of the asset not yet having a status at all. We do this by using an if statement, outputting Asset has no status if there is no status, and {{status.label | html.escape}} if there is. If you look in the documentation for the ComboValue type, you can see it has a label property. And again we remember to escape the user input, just to be on the safe side.
This concludes everything we need to do for the mail template. Make sure to save it, and put note down the name you gave the template, since we will need it for configuring the automation workflow.
Creating the automation workflow to send the email
This walkthrough focused mostly on the mail template, and will not dig into the details about how AW work, but will use a simple example for testing.
First create a trigger, in this example I’m listening for a change on the english description field. Normally you might use something like a Cron trigger to start the workflow, so it can run on a schedule.
Next i’m using a search to load the assets i want to display. I’m just using GetAssets here, since that search comes with the dam center. Normally you would want to make a custom search, so you can find just the assets you want to show.
Then i need to extract the asset ids from the json:
Next comes an oddity. Because the mail template workflows takes a list of items, it needs them formatted as a list it can parse. The way automation currently deals with this, is splitting the values on comma (,). So we need to create a string from the asset ids, separated by comma. We can do this using the Join Strings action:
Then we need to actually invoke the Send mail to member action:
We are going to be going through this action in detail, since it really is the meat of the workflow.
First we have the Receiver Member Id, which is simply the member id of the user who should receive this email. If you want to send an email to multiple users, you should invoke the action multiple times, once with each member id.
Next is the Template Name, which is the name you gave your email template.
After that is the Config Version Id, which is the config version id from the config manager you want the email to be send from. If you simply created your template in the root config version, then any values here will work, as long as it is a valid heirachy id, for example /0/.
Lastly is the Mail Data, which is the data that is passed along to the template. The syntax is a key-value syntax, which looks like this (key),(value). The key is what the name of the property on the data object will be in the mail template. The value is the data you want to pass along as a list. Data is always pass along as a list in the mail system. You can pass multiple key-value pairs along should you wish to. The ordering of the values will be preserved, when passed to the mail template.
This should be everything you need to, to have your system working.
Improving the performance of the mail template
If you run your mail template by loading 10 metafields for each assets, and loading 500 assets, it will ofcause take a bit of time, and put quite a bit of load on your dam center. To optimize your template we provide certain helper functions that will cause data to be bulk preloaded, which is must faster than loading each value as it is necessary.
At the time of writing Digizuite provides 3 functions for this:
preload_titlequeue_meta_field_loads_by_item_guidqueue_meta_field_loads_by_label_id
Each of these functions takes the assets to preload. You just need to call them once in the start of the mail, and they are safe to call multiple times.
preload_title is also recommended to use when using the get_link_to_asset_preview function, since it requires the title of the asset to work.
Using these functions properly can make almost any mail template execute instantly, with much less load on the dam center.
Things to be careful about
This sections tries to list out some of the things you should be aware of with the templating system.
Iteration limits
Scriban only allows each loop to run a maximum of 1000 times, after which it will stop execution and throw an error. To get around that you can use a limiting operator like this:
for assetId in data.assetIds limit:200
to only display the first 200 items.
It is also generally recommended that you keep the limit low, to both allow the template to execute faster, and to save the receiver some pain, since their mail client won’t start crying from too much mail.
Html escaping
It has been mentioned several times in this document, but make sure to escape any user input using | html.escape, otherwise you might introduce security issues. When in doubt, escape the value.