Basics:Snippets

From Cerberus Helpdesk Wiki

If you find yourself retyping the same responses over and over again, the snippet feature is a great alternative. A snippet is a saved template that can be reused -- you can interweave them into your replies with whatever original content you're writing, however many times you like. Because they are inserted as regular text directly into the text field, this means it's possible to trim down, flesh out, or clip a snippet together with another snippet inside the response itself, leaving the actual template as is.

Creating Templates

To create and manage your snippets use the dedicated 'Snippets' tab inside of 'mail'; this list will contain all the templates your workers created. Everyone can read or use a template, but only the original author or a Helpdesk administrator can edit it.

There are three contexts: Ticket, Worker, and Plaintext; we'll go over them shortly.

• We're going to build off the "New Order" template, select "Ticket" and click 'Add Snippet'.

We'll get back to the different types (Worker, Plaintext) shortly.

Tokens

Whatever message you place inside the 'Content' field will be saved as a template. See the dropdown and 'Test' button? In addition to straight text you can personalize a message by inserting tokens, or placeholders, to be swapped out with any corresponding fields in the Helpdesk.

Selecting one of these tokens places it into your template where it will {{look_like_this}}.

• Current:Worker is of course YOU, the logged in worker, who's replying and using the snippet. This template will give your customers a contact person in the company should they need to follow-up later.

• Only organizations are given a basic "phone" field, so I've created a Worker custom field to give each employee his own number (helpdesk setup->custom fields->worker). You do not need to preface custom fields with a *star, I did that to make custom fields stand out in our screenshots.

• The *Phone (Worker) custom field is represented by an internal ID inside the template as {{worker_worker_custom_18}}. At the moment this is just how it works and something you'll have to get accustomed to.

Once you've got your template reading like you want, the Test button will give you a live data preview by sampling one of the tickets in your Helpdesk, including those that are closed or deleted. This gives you an opportunity to check for any mistakes in your logic (a name should be here not a date) or any syntax errors (deleting a closed curly brace by accident).

Notice in the first screenshot I purposely left out the second "}" in "{{worker_first_name}".

Even if there's no errors, because the sampling is random you may get some _______ (blanks) where the real data should be. This can happen if you have a large desk where you haven't been filling in customer or ticket information regularly; nothing to worry about, just keep clicking the 'Test' button to pull in another ticket that's actually filled in.

I corrected the mistake. My (Joe's) phone number is pulled from a worker custom field.

• For now go ahead and give your template a title ("New Order") and save changes.

Contexts

Taking a step back. If you recall there were a few types of snippets we could have initially picked from -- we chose "Ticket" but there was also a "Worker" and "Plaintext" option. Each one refers to a specific context where the template can be used and consequently dictates what set of tokens you will have at your disposal (in the dropdown).

This is a truncated list but the real one includes much much more. Custom fields like *Support Package (Address) and *Phone (Worker) will appear in the list wherever applicable.

It's hard to appreciate how the new token system works unless you study it carefully, but notice the cascading effect that gives you access to the deepest fields in the Helpdesk. Most sources have a similar path, jumping from object to object to give you access to the low-level fields; e.g. (initial message->sender->organization->website) gets you a company's website through the sender's e-mail address.

Before we get too ahead of ourselves let's go over the snippet types, or contexts, one by one. Each indented bullet point refers to the actual tokens available.

• Ticket is the most all-encompassing context and includes any data associated with tickets and the e-mails themselves.
  • Ticket: group, bucket, mask, subject, updated ...
  • Assignee (Next Worker): e-mail, name, title, organization (address, phone number) ...
  • Current Worker (You): e-mail, name, title, organization ...
  • Initial/Latest Message: content, created, sender (e-mail, name, organization) ...
  • Any Custom Fields that can be tied to the other sources (ticket, worker, address (senders/workers), organization)

• Worker is the next context down so to speak and only includes worker-level fields.
  • Current Worker (You): e-mail, name, title, organization ...
  • Any Custom Fields that can be tied to the other sources (worker, address (workers), organization)

• Plaintext is exactly what it sounds like, a barebones context that does not use tokens at all. This is good for generic responses without any personal details.

So the question is why did we choose to split up snippets like this? The answer, contexts force tokens to only show up where they're relevant.

"Ticket" snippets obviously require a ticket to draw from, this means it only works with replies and NOT with Send Mail or Open Ticket where the ticket hasn't been formed yet. And while the name doesn't exactly imply it, "Worker" snippets DO work with replies, Send Mail, and Open Ticket. "Plaintext" being the least strict naturally works with all three as well.

The other reason for creating multiple contexts at this stage may have something to do with planning ahead. Down the road we'll likely extend templates to other areas of the Helpdesk and the same context problem would exist -- tasks wouldn't necessarily mesh with tickets and we'd probably need to create a dedicated 'Tasks' context ('Plaintext' will always be the universal piece that works everywhere). The bottom line is the templates in 'Snippets' are still limited to just e-mails, but expect that to change later on.

Advanced Conditional Logic

Aside from just tokens, snippets are even more flexible with the new conditional logic the developers added. Thanks to the Twig template language now under the hood, this functionality allows you to meticulously control what your templates say based on any criteria you can come up with. This effectively lets you write very "generic" templates which can be applied in multiple circumstances or customer scenarios.

To explain some of the Twig syntax in detail we'll extend our "New Order" template, go ahead and re-open it. Let's assume we have a handful of orders in our Sales group:

Tickets were generated using the helpdesk setup, Simulator tab with "Web Hosting" sample data.

• Customers could choose between four packages: Platinum, Gold, Silver, and Copper.

• Each ticket was created using the Simulator plug-in therefore they have a predictable subject pattern -- New Order: domain (type of package). We'll capitalize on the fact you can determine the chosen package directly from the subject line.

• You are NOT assigned the tickets; the "next worker" is John Smith.

So here's the improved template we're working with.

I've intentionally added extra line breaks to make the example easier to follow, but the spacing will affect the actual template. So in practical use you may want to remove any unneeded line breaks to prevent "double spacing".

The following three Twig conventions are probably all you'll ever need to work with, but there is documentation should you want to experiment with other syntax (for loops, variables, comments, etc).

DATE MODIFIERS

• Your order was received on {{initial_message_created|date("m/d/Y")}} ...

Every token you insert that represents a date and time will include a default "date" filter (no parentheses), which will output something like July 14, 2010 20:51 . However these tokens can always be modified to display whatever you like in any format you want by defining a ("style"). In our example we chose to go without an actual time of day and only use the typical American month and day "m/d/Y", but other possibilities include:

• date("Y-m-d") :: 2010-07-14
• date("D M d") :: Fri Jul 14
• date("h:m A") :: 08:51 PM
• date("h:m P") :: 08:51 -07:00

Note: There is a pipe "|" character (SHIFT+\) separating the token and date filter, this replaces the ending curly braces around the token name itself.

DEFAULTS

• If you have any questions, please call {{assignee_first_name|default(worker_first_name)}} {{assignee_last_name|default(worker_last_name)}} ...

If the token you're using points to an unfilled field you might end up with _______ (blanks) peppered throughout your message, which as we discussed earlier regarding the Test button can be quite common in busy desks with lots of fields or custom fields. To work around this problem you can fallback on a different token or generic text, e.g. "Hi there!".

In our example "if the ticket is already assigned to a worker (John Smith), print his information, otherwise show my (Joe's) information". The idea is whoever is assigned a ticket should have his or her contact information sent back to the customer instead of our own. That way when it gets a little busy at the office, or someone's on vacation, should another worker need to reply they can do so, letting the customer resume their conversation with the original worker assigned to the ticket. The "default" filter is for handling unassigned tickets where it's appropriate to include the replying (current) worker's contact details. John Smith was assigned to all of our new order tickets, so no matter who replies John's still the team's salesman.

Note: Just like date there's a pipe character in front of default; don't forget to add it yourself because unlike date, "default" isn't automatically appended to your tokens. Also, if you use a token inside the default(...) filter make sure you remove the double curly braces around the token, default(worker_first_name).

IF/ELSE

• {% if 'Platinum' in subject %} ... {% elseif 'Gold' in subject %} ... {% endif %}

The sample code sort of speaks for itself, "if A is true then do B, if not check if X is true, if it is do Y". In our example we know all the possible conditions -- each new order fits the same subject pattern and we only have a few preset "packages" to choose from. This makes it easy to look for the appropriate match inside the {{subject}} and determine what level of support people qualify for. If all goes well the corresponding block of text should be dropped into your snippet ("As a 'Gold' customer you qualify for..."). As always use the 'Test' button to see if you're getting the expected results with different tickets.

Note: The statements are bookended by {% %}, 'in' is a mandatory keyword, and the "endif" is used to close the entire conditional block. Because tokens like {{subject}} are automatically inserted with double curly braces, you do need to remember to delete them from inside the if/else statements.

Using Templates

Once you have created a snippet it's time to put it to use. Inside every ticket's reply box there will be a Snippets button to show all your existing templates. Now we are using a "Ticket"-based snippet which means it will work only with replies. As we mentioned earlier, when composing new messages through either Open Ticket or Send Mail you can only use a '"Worker" or "Plaintext" snippet.

• Click the 'Snippets' button to open the "insert snippets" window.

By default the most popular, or frequently used, entries are up top, but you can tweak the sort order or do a quick search to pinpoint a specific template.

(peek) will show you the literal template so you can check if it's the right one. Even though it may look like it, you can not edit the templates inside the (peek) window; go back to the 'mail', 'Snippets' tab if you want to make some changes.

Finally, clicking the snippet name will insert a copy of the template with all the token logic replaced. Because we're working with text and the snippets window stays open until you close it, it's very easy to include multiple templates wherever you want by continuously moving the text cursor around and clicking a different snippet.

Snippets functionality in other places

Snippets has sort of a double meaning in Cerb5 and it's worth separating the two concepts for clarity. Snippet Templates is what most users associate the term "snippets" with, and it's what we've been constructing thus far with our new order example. These constructs replaced 4.x's E-mail Templates; the name change was to emphasize the direction we're going with more multi-purpose templates.

The other half of "snippets" is the core functionality templates are built on, specifically the contextual tokens and conditional logic from Twig (date modifiers, defaults, if/else). Yes the two "snippet" halves clearly work in tandem, but we need to conceptually distinguish them because these tools have been incorporated into other features. We've swapped out the old token system inside signatures and auto-responses and replaced it with the different snippets contexts, plus developed it into the new 5.x feature called Broadcast. Remember you don't have access to the actual 'mail' templates, the auto-responses are now just equipped with "Ticket" tokens and signatures with "Worker" tokens.

What does this mean for you? Well even if you don't take advantage of the conditional logic, the snippet tokens by themselves offer a lot more fields to play with thanks to the extended reach of contexts. A couple of new things are possible.

More personalized worker signatures

Recall the *Phone (Worker) custom field we created at the beginning to give each employee his own phone number, {{worker_worker_custom_18}} . After you assign them a number inside 'helpdesk setup', 'Workers', it's ready for use in your signatures.

Previous versions only included: worker name and title. This is a screenshot of group signatures but the same can be applied to default signatures in 'Mail Setup'.

Auto-responses targeting specific contacts

The *Support Package (Address) custom field designates a service priority for each sender, {{initial_message_sender_custom_19}} -- when a new customer signed up for one of our packages we assigned their e-mail address a status. Gold customers get a special auto-response urging them to call the office should their support ticket go unanswered.

Previous versions only included: date, requester, ticket mask, subject, and body. This is a screenshot of "new ticket" auto-responses but the same can be applied to "close ticket" auto-responses.

Broadcast to multiple tickets at once

Broadcast enables you to reply (or compose new tickets) in bulk with a generic or targeted response. You could for example send out a product announcement that reads the same for everyone, or apply the snippet toolkit to make it more relevant to the intended recipient ("As a recent 4.x customer you qualify for a free 5.x upgrade"). Another good fit for broadcast is processing a batch of new orders like we've been doing already.

Unfortunately despite the fact broadcast produces regular e-mail, the templates themselves are not accessible so we can't use our "New Order" template (see CHD-1985). The best we can do at the moment is copy it from the 'Snippets' area beforehand and then paste it directly into the reply box.

I've created a 'Processed' bucket to archive all the paid orders.