Setup

Setting up URL Builder Pro involves configuring the names and destinations of links you want to show to agents. You'll be asked to provide this when installing URL Builder Pro. Afterwards you can edit this any time from the app settings.

Link Configuration Overview

Links are configured using JSON. Note that URL Builder Pro is largely backward compatible with URL Builder. This means you can copy your old config and everything should work.

In this example, suppose we want 2 links and we have a custom field, 360015176234, which is our internal customer ID for the user.

1. LinkedIn (https://www.linkedin.com/search/results/all/?keywords=[Customer Name Here])

2. Purchase History (https://example.com/user/[customer id here]/order_history)

The JSON we would enter for this is...

[
  {
    "title": "LinkedIn",
    "url": "https://www.linkedin.com/search/results/all/?keywords={{ticket.requester.name}}"
  },
  {
    "title": "Purchase History",
    "url": "https://example.com/user/{{ticket.custom_field_360015176234}}/order_history"
  }
]

Link Configuration Details

The link configuration is a JSON array of objects. Optional config exists, but each object must contain title and url. Optional values are condition and color. These are included alongside the title and url.

Here is an example of an entry with all possible configuration properties. This entry represents a green button that only shows up when the current ticket is assigned to the sales team. The button's name is "Sales History" and it will take you to a sales report based on a custom field representing the users internal customer ID for your order management system. See the individual sections below for an explanation of each property.

[
  {
    "title": "Sales History",
    "url": "https://www.example.com/admin/sales_report/{{ticket.custom_field_360015176234}}",
    "color": "green",
    "condition": "ticket.assignee.group.name == 'Sales'",
    "target": "salesTab",
    "location": "ticket"
  }
]

title

The name shown to agents. This can contain ticket values in {{double braces}}.

url

The url agents are taken to. This can contain ticket values in {{double braces}}.

condition

If a condition is given, the link will only appear if the condition is met. Note that double braces are not necessary for conditions. Conditions are written with javascript syntax. Operators such as equality (==), inequality (!=), comparisons (>, <, >=, <=) and boolean logic (&&, ||) are all permitted. Example conditions are...

ticket.assignee.group == "Sales" // Only show if the assigned group is sales
ticket.custom_field_360015176234 != null // Only show if the custom field is present

If you try to access a value that doesn't exist, the link will not appear. For example, if a ticket is only assigned to a group and your condition tries to access ticket.assignee.user, it will not show up.

color

The default color for buttons is blue. You can use any of the following colors: red, orange, yellow, green, blue, purple. Color is useful for differentiating links, or giving similar links the same color.

target

Target is an html attribute on links which tells the browser where to open the link. You can read more about it in Mozilla's documentation. By default, every link in url builder will open in a new tab. If you give a custom target, any links with that same target will open that same tab and navigate to the page, rather than opening a brand new tab. This can contain ticket values in {{double braces}}.

location

Location can be either "ticket" or "user", depending on wether you want the link to appear on the app sidebar when viewing tickets or users. By default links will appear on the ticket sidebar. Specifying "user" will make the link appear in the users sidebar instead.

Ticket Values 

The following ticket values are supported for links that appear on the ticket sidebar. For a comprehensive list, see: https://developer.zendesk.com/apps/docs/support-api/ticket_sidebar#ticket-object

ticket.assignee.group.id
ticket.assignee.group.name
ticket.assignee.user.id
ticket.assignee.user.name
ticket.assignee.user.email
ticket.assignee.user.role
ticket.brand.id
ticket.brand.name
ticket.brand.subdomain
ticket.brand.url
ticket.collaborators (array)
ticket.comment.text
ticket.comments (array)
ticket.createdAt
ticket.custom_field_12345 (Where 12345 is the ID of your custom field)
ticket.description
ticket.due_date
ticket.externalId
ticket.form
ticket.id
ticket.isNew
ticket.organization
ticket.organization.organization_fields.fieldName (where fieldName is your custom organization field)
ticket.postSaveAction
ticket.priority
ticket.recipient
ticket.requester.email
ticket.requester.externalId
ticket.requester.groups (array)
ticket.requester.id
ticket.requester.name
ticket.requester.notes
ticket.requester.user_fields.fieldName (where fieldName is your custom user field)
ticket.sharedWith
ticket.status
ticket.subject
ticket.tags (array)
ticket.type
ticket.updatedAt
ticket.viewers (array)

User Values 

The following user values are supported for links that appear in the user sidebar. For a comprehensive list, see: https://developer.zendesk.com/apps/docs/support-api/ticket_sidebar#ticket-object

user.id
user.email
user.groups (array)
user.organizations (array)
user.identities (array)
user.name
user.role
user.externalId
user.locale
user.details
user.notes
user.alias
user.signature
user.timeZone
user.tags (array)
user.avatarUrl
user.custom_field_name (Where custom_field_name is the name of a custom user field)

Current User 

In all locations, you can use current_user to access the currently signed in agent. All of the values from the User Values section above are available. 

Troubleshooting

If none of your links are showing up when you expect them to, it's possible that the JSON is malformed. You can quickly check your JSON by validating it on this website: https://jsonformatter.curiousconcept.com/

If a specific link isn't showing up, it's possible a value you're checking doesn't exist. Double check the spelling of the substituted values, in particular custom fields.