Using placeholders

Using placeholders

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.<key_name>}}
Organization custom fields {{ticket.organization.custom_fields.<key_name>}}

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 displayed 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.

Have more questions? Submit a request

Comments

  • Avatar
    Jonathan March
  • Avatar
    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

  • Avatar
    Antonio Gutierrez

    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.  

  • Avatar
    Suzana Bueno

    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?

  • Avatar
    Bob Novak

    @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

     

     

  • Avatar
    Evelyn Yoder

    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?

  • Avatar
    Dr. J

    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.

  • Avatar
    Evelyn Yoder

    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.

  • Avatar
    Dr. J

    @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. :)

  • Avatar
    Sandie

    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. 

  • Avatar
    Avi Warner

    @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?

     

  • Avatar
    Sandie

    @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...

  • Avatar
    Avi Warner

    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). 

  • Avatar
    Adrian Dryglas

    Hi,

    can I add multiple placeholders?

    For Example:

    Request number #{{ticket.id}} has been received: {{ticket.ticket_field_<field ID number>}}, {{ticket.ticket_field_<field ID number>}}

    Last two place holders are just fields I have created for Requesters to fill in when submitting tickets via portal.

    Thanks.

    Adrian

  • Avatar
    Emily

    Hi Adrian, 

    You can add as many placeholders as you'd like to a single business rule notification, macro or ticket comment!

  • Avatar
    Karyn Tooke

    Hi - when I use the custom field placeholder {{ticket.ticketfield<field ID number>}} it returns the tag instead of the drop down value, is that correct?

  • Avatar
    Jessie Schutz

    Hi Karyn! Sorry for the delayed response here!

    I did some testing on this. When I inserted a custom field placeholder into the email body of a notification trigger, it inserted the actual drop-down selection, rather than the tag. However, this might vary depending on where you're putting the placeholder. Can you tell me where you're using the placeholder so I can test and verify?

    Thanks!

  • Avatar
    Jonathan March

    Kathryn, looks like you might be omitting "-option-title"? See the placeholder docs; search for "ticket.ticket-field-option-title-ID" (Substitute underscore for hyphen, which I had to use to avoid butchery by the forum markdown.)

  • Avatar
    Karyn Tooke

    Hi Jonathan - thats it!! thanks alot :-)

Please sign in to leave a comment.