Forums/Documentation/Managing your support workflow

Using placeholders

Anton de Young
posted this on April 07, 2011 08:54

Placeholders are references to ticket and user data that you include in the subject and text of email notifications. Without them it would be impossible to create automated messages. Here’s an example of how placeholders are used in an email notification:

The placeholders are contained within matched double curly brackets and are, in this example, references to ticket properties. When you’re composing email notifications, you can view the list of placeholders by clicking View Available Placeholders.

For the complete list of placeholders, see Zendesk data object (placeholders) reference.

Using placeholders for custom fields

Placeholders are generated automatically by Zendesk, based on the ticket and current user properties. These are referred to as system placeholders.

When you add custom fields for tickets, users, or organizations, they are also available as placeholders. You can use placeholders for your custom fields as you would any other system placeholder.

Every custom field has a unique ID or key. When you create a custom ticket field, the ID is automatically generate for you. When you create a custom user or custom org field, you enter a unique key that cannot be edited once it is set.

Custom fields are not included in the list of available placeholders, but they follow this simple naming pattern that references their unique ID or key.

Ticket custom fields {{ticket.ticket_field_<field ID number>}}
User custom fields {{ticket.requester.custom_fields.<field_key>}}
Organization custom fields {{ticket.organization.custom_fields.<field_key>}}

For example, a custom ticket field like this has the following placeholder:

{{ticket.ticket_field_505156}}

The placeholder name for the options in a custom drop-down list follows a different pattern. There's only one placeholder for all three drop-down list options because this is a reference to the option that was selected. The ID is for the custom drop-down list because options do not have IDs. Again, this is a reference to the single option that was selected.

Ticket custom drop-down fields {{ticket.ticket_field_option_title_<field ID number>}}
User custom drop-down fields {{ticket.requester.custom_fields.<field_key>.title}}
Organization custom drop-down fields {{ticket.organization.custom_fields.<field_key>.title}}

For example, the placeholder for a drop-down list for a custom ticket field would look like this:

{{ticket.ticket_field_option_title_515416}}

To find the ID for a custom ticket field

  1. Click the Admin icon () from the sidebar, then select Ticket Fields.
    Zendesk Classic: Select the Manage menu, then select Ticket Fields.
  2. Locate your custom field in the list and then click Edit.
    The ID is appears in the right column:

To find the key for a custom user field or a custom organization field

  1. Click the Admin icon () from the sidebar, then select User Fields or Organization Fields.
    Zendesk Classic: Custom user fields and custom organization fields are not available in Zendesk Classic.
  2. Click the name of a custom field.

    The field key appears in the properties panel on the right.

 

Comments

User photo
Jonathan March
Enthought

Would it help to mention Liquid Markup here, with this link? https://support.zendesk.com/entries/20134837-using-liquid-markup-to...

July 28, 2012 16:17
User photo
Jochsner

Anton I'm not sure when this started but I just noticed that the sidebar ID for the div containing the custom field id reference has a display property set to none.  I'm using the new ZenDesk.

html body.ticket_fields div#page div div#container.clearfix div#sidebar

March 05, 2013 11:22
User photo
Antonio Gutierrez
vits

I'm using the new Zendesk and I have the same issue.  Jochsner, thanks to your captures. I was able to figure out my placeholder ID.  

April 02, 2013 06:03
User photo
Suzana Bueno
movile

The dropdown placeholder, when used, posts the whole dropdown field tree instead of only the last option. For example, instead of posting "C", it posts "A::B::C" due to the way we organized this field.

 

Is there any way to fix this and use only the last value, while maintaining the field organization?

July 17, 2013 09:37
User photo
Bob Novak
Zendesk

@Suzana, You can do this by using Liquid Markup. Your standard placeholder for a custom dropdown ticket field would be {{ticket.ticket_field_<field ID number>}}. To modify that, change it to the following: {{ticket.ticket_field_<field ID number> | split: "::" | last}}.

The split function will divide your placeholder at the locations of whatever is in quotes. Last displays the final element divided this way, and first displays the first if you want that. Getting something in the middle is more complicated, but it doesn't sound like you need that

 

 

July 26, 2013 14:36
User photo
Evelyn Yoder
activevideo

Thanks @Jonathan and @Bob - Liquid Markup + the "split" function is just what I needed.

Any chance we can use this to select fields in views/reports?

August 08, 2013 11:13
User photo
Dr. J
Zendesk

Hi Evelyn - great question! - I'm not 100% clear on what you'd like to do here, but it sounds like you'd like to use Liquid Markup to modify a report/view?  Since a view/report is essentially static - e.g. you've preset what you want in the admin settings, and the report is then generated by the system, I don't think you'd be able to use liquid markup to modify the selections for your reports/views.

August 15, 2013 08:52
User photo
Evelyn Yoder
activevideo

Dr J - thanks for the response!

To clarify, we want a view (or report) that groups tickets based on values in a nested field, and we want to show only part of the nested value, not the "category::subcategory" format.

For example, if the nested field values are: "Product X::Model1", "ProductX::Model2", "Product Y::ModelA", etc., then we only want to show "Model1", "ModelA". We're told this might be possible with GoodData, but we haven't explored that app yet.

August 15, 2013 22:17
User photo
Dr. J
Zendesk

@Evelyn - Every field selection form a drop-down menu generates a Tag.  Make sure you have Tags Enabled, then you can use those tags in your reporting. :)

August 19, 2013 11:39
User photo
Sandie
sandiehughes

I've added a custom organization field, lets call it Xyz, and it's field key is xyz. I'd like to add it to a macro that will be used to create a ticket sent to a user. So far I've tried a ridiculous number of variations and nothing is displayed. The most logical variations I've already tried would be these:

{{ticket.requester.custom_field.xyz}}
{{ticket.requester.custom_fields.xyz}}

{{ticket.organization.custom_field.xyz}}
{{ticket.organization.custom_fields.xyz}}

{{ticket.ticket_field_xyz}}

Please can someone tell me what syntax I need to use?

Also, may I suggest that rather than just showing the unique part of the field key in the custom field management area, it would be so much more helpful if you showed the entire placeholder. 

November 07, 2013 05:00
User photo
Avi Warner
Zendesk

@Sandie, for an organization field, it should be {{ticket.organization.custom_fields.xyz}}. Can you let me know if you're applying the macro on a brand new or an existing ticket? Organization isn't actually set on a ticket until it's created (because it's attached to the requester not ticket record). Is the value showing up if you apply the macro on an existing ticket?

 

November 10, 2013 14:54
User photo
Sandie
sandiehughes

@Avi, thanks for the response. Having now tried it, it does in fact work fine on a ticket response, but not on a new ticket! The information I'm adding to the custom fields 'belongs' at organisation level, is there a way to add organisation level information that I can use in a ticket an agent generates? I'd prefer not to move the information to the individual level, as I suspect I'll regret it at some point in the future, but I'm about to try...

November 11, 2013 01:42
User photo
Avi Warner
Zendesk

Sandie, unfortunately when creating a new ticket, even after setting a ticket requester (or associated organization), the organization is actually not yet set for that ticket and our system is unable to pull related placeholders. Really sorry about this. At the moment, they're only able to work properly on existing tickets (after the organization ID has been set on that ticket). I'd recommend sharing your use case on our Product Feedback forum here: https://support.zendesk.com/forums/1848-Product-Feedback

Again, sorry for the less than positive answer here, although your use case is certainly a valid one (and even more useful now that we have custom user and organization fields). 

November 21, 2013 07:42