Using the Brand Manager app

The brand manager app builds on an existing workaround in Zendesk that makes it possible to control the look and feel of email notifications using Liquid markup conditions in triggers and automations. Please be aware that there are limitations on what this app can do.

The way these conditions work is that in each trigger or automation, there are rules that state if the brand = A then use this HTML, and if the brand = B then use this other HTML. This has been documented in articles on Zendesk communities like this one. 

The issue with this workaround is that if you want to update the look of a brand then you need to update all of your triggers & automations which can be time-consuming and prone to errors.

This is where the brand manager app can help. It allows you to update everything in a single click. 

But how does it do this?

It breaks your {{content}} placeholder into more parts.

The Zendesk global email template is a single bit of HTML that lets you control what all of your emails look like. Within this global email template you will find the {{content}} placeholder. This placeholder is what pulls in your email notification content as defined in your triggers and automations. 

The brand manager app takes the contents of your triggers and automation (ie. the contents of {{content}} ) and breaks it down into more parts. Let's have a look at the structure first:

As you can see from the structure above, the "Band manager template" feeds into your triggers. And within that template, it uses placeholders to pull information as needed.

Now that we've defined how the app fits together, let's go about setting up your branding. 

Step 1: The 'global email template'

The global email template is what defines the look and feel of all emails sent out of your helpdesk. In order to customise look for each brand, we'll need to move the brand centric HTML out of the global template and over to the app. It's a bit of a tricky decision as to which code to pull out because we also need to make sure that emails that rely only on your global email template look ok too (ie. are not sent by a trigger or automation - that's right, system emails like 'password reset' or 'CC's' can not be branded - see here for more details).

You can edit your global template by clicking the cog on the left of the screen, then under "Channels" click on "Email". Then on the right, scroll down to the "Email Templates" section.

If you'd like to use some example code, at the bottom of this article, you'll find a couple of files attached. One of them is an example "global template". Copy and paste this code into your Zendesk email template and click save. By doing this, any emails that now get sent out of you Zendesk will look like this: 

Now that there isn't any brand HTML in the global email template, we can go about adding it within the app.

Step 2: Adding the 'Base template' in the app

The next step is to define the rest of your email template. (Note that we're not doing anything brand specific yet, we're still laying the foundation.) To do this click on the brand icon on the left of the screen and then on the 'settings' tab like this: 

Then add in the template HTML. Where ever you want the actual text of your trigger or automation to appear, put in the {{content}} placeholder. Where ever you're planning to use branded HTML, add either the placeholder {{brandHeader}} or {{brandFooter}}.

Note: You can only use each placeholder once (This means there are only two spots you'll be able to use branded HTML).

Also note: What ever code you plan to use in the {{brandHeader}} and {{brandFooter}} placeholders, you should keep it as concise as possible.

Once you're happy with the HTML in the base template, at the bottom click 'Save & update'.

Step 3: Defining the branded HTML

Now that we've prepared the global template and the base template in the app, you can now define the html unique to each brand. 

You can set this by clicking on the 'brand templates' tab, and then click on the edit button on the right for the brand you want to setup first. 

Here you'll be able to upload a logo.

You'll also be able to define the HTML for each of the placeholders {{brandHeader}} & {{brandFooter}} (1). And to reference logos URL simply use the placeholder {{logoURL}} (2) - (to make it appear as an image, make sure it's used inside an <img> tag).

Then check the "Custom branding" box (3) for the app to start using this code live in your triggers.

Finally, click on "Save and update X triggers" (4) at the bottom.

Note: As mentioned above, the brand code should be as concise as possible, as this is the code that will be part of the conditions added to your triggers. If you have a footer that is 1000 characters for each brand, then that code will be repeated in the trigger for as many brands as you have. 5 brands would mean 5000 characters. Since the maximum length of a trigger is 8192, this would probably limit the number of brands you could use to about about 6 depending on the size of your base template & notification content.

One way you can help keep the code concise that we've used in the examples, is that rather than placing the full img tag into the header like this:

<img align="center" height="60" class="img" src="{{logoURL}}">

Since none of the code changes from brand to brand, we've moved all of it but the{{logoURL}} placeholder into the base template as you can see under step 2 of this article. 

Also note: You may see that it says "Save and update 0 triggers and 0 automations". So, why is it telling you it's not going to update any triggers? Well, in order to help you to be sure of the changes you're making, we've built the app so you can select which triggers you want the branding to work on under the "Notification content" tab. That way you can test things out on a trigger of your choice before pushing it across all of your triggers. 

Step 3: Define what you want to say & deploy branding to triggers

The "Notification Content" tab lists all of the triggers on your helpdesk that send emails out (Note: This does not include targets).

To edit what the trigger says and to start using branding simply click 'Edit' next to the desired trigger like this: 

Then on the next screen, check "Enable branding" to start using branding with this trigger, confirm what your trigger will say, and click save: 

Now on the main "Notification content" screen, you'll note that in the custom branding column, there is a tick next to the trigger you just enabled like this: 

Now try testing out the trigger you just enabled. If you've used the example code attached and have uploaded a logo for your brands, your email might look something like this: 

Much nicer than before right? 

Cool!

Step 4: Setting the fallback branding

So now you might be wondering, what happens if I send an email to a brand where branding hasn't been switched on?

For example, in the image below you can see that only one of the brands has been switched on. The other ones aren't being used yet.

So, if you were to send an email into 'Help Desk' or 'Sales Desk' what would the email look like? Well, this is where your 'fallback branding' comes in.

You can set this by clicking on the 'Settings' tab, and then below the 'Base template' box, you'll see you can define the header and footer HTML the same as you set your header and footer HTML for any other brand. 

Now if you send an email from a non-branded brand it's still look presentable thanks to your fallback branding HTML :-)