Custom fields in Tickets

[Important]Important

If you rely on custom fields to collect mandatory, additional information when a user is submitting a new ticket you MUST NOT enable Akeeba Ticket System's new ticket by email feature (it's okay to allow replies by email). The reason should be pretty obvious: when a new ticket is created by email the custom fields CAN NOT be populated since there is no standard way to extract this information from a ticket.

Likewise, if you want to use custom fields as conditional fields (a set of custom fields “opens” for editing by the client when the support staff toggles another staff–only custom field) you should disable ticket replies by email OR make it clear to your users that they can only enter this information when they edit the ticket on your site.

Custom fields are very powerful but they only work in the web interface. Creating and replying to tickets over email is very convenient but cannot use custom fields. Power or convenience — or something in between? Choose wisely. It's ultimately up to you. You know your use case better than we possibly can!

And no, there really is no way to reliably populate custom fields from emails. We experimented with various ideas but they are all as good as a bouncy ball filled with nitroglycerin. That is to say, it sounds like a cool idea until you try it for real and regret it instantly...

Akeeba Ticket System has full support for Joomla Fields in tickets. Before you start using them you need to keep in mind a few basic concepts.

Custom fields can be limited for editing in the backend, frontend or both sides of your site. This is controlled by the field's Editable In option. If you want your support staff or your clients to be able to change this field's value in the frontend of your site you need to set this option to Site or Both. If you want your backend support staff to also be able to edit this field's value you need to set this option to Both.

Custom fields are by default only editable by Super Users. This makes them kinda useless. Remember to go to the Permissions tab in each field and select which user groups can edit them by allowing the Edit Custom Field Value permission. This is an extremely powerful setting with a very interesting repercussion. You can make a field editable ONLY by clients, ONLY by support staff, neither or both! A field only editable by a client would be ideal for a privacy consent or NDA agreement field which needs to be legally guaranteed to be set only by the affected party (the client). A field only editable by the support staff would be ideal for implementing conditional fields. We will see example of these further down this documentation.

Read–only fields are, by default, visible in the ticket edit form in the frontend and backend of your site. You can hide these fields by setting the Display When Read–Only option of the field to No. This would be necessary for fields meant to be only accessed by your support staff or generally for fields you don't want to clutter the edit ticket interface, something which could overwhelm the client.

Fields have an access level which controls when they are displayed. This applies to rendering the field value (and also making it accessible through the ticket's jcfields property for template overrides) when displaying the posts of a ticket AND when editing a ticket. By default this is set to Public which means that everyone, including Guest users, can see the fields. Please note that Joomla CANNOT limit the display of custom fields only to ticket staff and the ticket owner i.e. it's impossible to implement Akeeba Ticket System's “Private” visibility. The best you can do is EITHER set the field's Access to a view access level which only includes the support staff OR set the ticket's Automatic Display to Do not automatically display. In the former case only support staff will see the custom field contents, even if the client can edit it. In the latter case neither will see the custom field contents unless they edit the ticket. This kind of limited display is great when asking for privileged information like server access details, social security numbers etc.

[Note]Note

Super Users are special in Joomla. They can view and edit any field, regardless of the Access and Permissions of the field itself.

We understand that this is confusing but it's not a bug in Akeeba Ticket System. It's how Joomla itself works.

We strongly advise AGAINST using a Super User account to manage tickets. Even if you are the sole privileged user on your site we recommend creating a new, unprivileged user account and assign it to a group which has its Support Staff privilege allowed. Using this new account to reply to and manage tickets will be much easier when it comes to custom fields — and more secure, too!

Fields can optionally belong to a Field Group. You can have as many field groups as you want. When submitting a new ticket or editing a ticket the fields are displayed per field group. Each field group renders a card (a bordered area within the form) whose title is the field group's title. If you have a field group description it will be displayed as an information message below the group's title and before any fields. This is a convenient way to include a brief explanation of why you are asking for this information and/or short instructions for filling out the fields in the group.

Finally, fields can be assigned to one or more ATS categories. The default is All which means that the custom field appears in all ATS categories. You can change that so only the most pertinent fields appear in each category. Please note that field groups cannot be assigned in a category. However, empty field groups ARE NOT displayed.

Conditional fields — Joomla 4.3

If you are using Joomla 4.3 or any later version, rejoice! Joomla supports conditional fields, i.e. displaying a field based on the value of another field.

[Important]Important

You do NOT need to use the Content – Akeeba Ticket System Custom Fields Show–on Behavior plugin with Joomla 4.3 and later.

When setting up a field go to its Options tab and set the display condition in the Showon Attribute option. This feature is handled by Joomla itself. The format of this option's contents and how it works can be found in the Joomla Showon documentation page. Please remember that you need to use the field names, not titles or labels, in the Showon Attribute field.

If you have already set up conditional custom fields in Akeeba Ticket System using Joomla 4.0–4.2 on your site you will need to migrate them to the new format. Here's what to do:

Migrating conditional custom fields to the Joomla 4.3

  1. Upgrade your site to Joomla 4.3 or later.

  2. Make sure the Content – Akeeba Ticket System Custom Fields Show–on Behavior plugin is enabled.

  3. Go to Components, Akeeba Ticket System, Fields.

  4. Edit every conditional custom field. For each field, cut the contents of the Show On option in the General tab and paste them into the Showon Attribute in the Options tab.

  5. Disable the Content – Akeeba Ticket System Custom Fields Show–on Behavior plugin.

Please note that the Content – Akeeba Ticket System Custom Fields Show–on Behavior plugin will be removed around September or October 2023 when we remove support for Joomla 4.2 in our software.

Conditional fields — Joomla 4.0 to 4.2 inclusive

By default, Joomla fields in Joomla 4.2 and earlier do not allow you to display them conditionally i.e. based on the value of another field. We found this to be rather limiting. We addressed this shortcoming with the Content – Akeeba Ticket System Custom Fields Show–on Behavior plugin. This plugin is installed and enabled by default when you install Akeeba Ticket System.

The plugin adds a new option in the General tab of the fields you define in Akeeba Ticket System only. It does not apply to fields defined for any other component, including the build–in Joomla components such as Articles, Banners, Contacts etc.

The plugin merely exposes to you a built–in Joomla feature. That's right, Joomla 4.0–4.2 already has a “show on” behavior, it just doesn't expose it for custom fields. The format of this option's contents and how it works can be found in the Joomla Showon documentation page. Please remember that you need to use the field names, not titles or labels, in the Show On field.

For example, if you have a List custom field with the name showme and you want to make another field display only when the showme field is set to 1 you need to enter the following Show On option value in the other field showme:1. We will see a practical example of this in the conditional fields tutorial further below.

[Important]Important

What you enter in this field is CODE, NOT PROSE. As a result, the letter case and the use of whitespace (or lack thereof) matters!

If your have a field the name of which is showme (all lowercase) then you must enter the Show On option as showme:1 in all lowercase, without spaces. The following things will not work:

  • Show Me:1 There is no such field as capital S followed by how followed by space followed by capital M followed by e.

  • ShowMe:1 There is no such field as capital S followed by how followed by capital M followed by e.

  • showme : 1 There is no such field as showme followed by space.

Likewise the bitwise operators [OR] and [AND] must be entered exactly like that: opening square bracket followed by uppercase OR followed by closing square bracket; and opening square bracket followed by uppercase OR followed by closing square bracket. No spaces, no other whitespace, no lowercase characters, no non-Latin characters. The latter is very important because of homoglyphs (different characters which look alike) such as the letters A (capital Latin letter a) and Α (capital Greek letter alpha) or O (capital Latin letter o), Ο (capital Greek letter omikron) and 0 (number zero). You must not have spaces before or after [OR] and [AND].

Finally, remember that you are entering the field's name, not its title or label. The field's title is something you see in the backend Fields page and it's just for your information. The field's label is what is displayed in the form itself. The field's name is a unique identifier. Different fields can have the same title and/or label but they CAN NOT have the same name. That's why Joomla's Show On feature operates on the field's name, not its title or label.

Fields in template overrides

If you want to use custom fields in view template overrides just remember that the ticket object has the same jcfields property you get in Joomla core articles. This property includes the field values of all fields which would be visible to the user regardless of their Automatic Display setting i.e. it includes fields whose Automatic Display is set to Do Not Display.

For those of you implementing view template overrides we have added a handy dandy helper to make your life managing fields much easier. Joomla keys the jcfields array by field ID which is cumbersome and practically unusable — you typically want to get a custom field by name. To help with that we implemented the getFieldsByName helper.

If you have the ticket in a variable named $ticket and you want to get the information for a field called example on this ticket all you need to do is $exampleField = $this->getFieldsByName($ticket, 'example'); . This returns the object with the field information and value. The raw field value is accessible as $exampleField->rawvalue whereas the fully rendered HTML of the field display is accessible as $exampleField->value.

If the field you are looking for does not exist the field helper will return null.

If you want to get the entire jcfields array keyed by the field name instead of the field ID you just need to omit the second parameter. For example: $allFields = $this->getFieldsByName($ticket);.

So, if you want to display the rendered version of a field named video only when the custom field with the name showVideo is set to 1 you can do this in your template override:

<?php if ($this->getFieldsByName($ticket, 'showVideo')->rawvalue == 1) {
  echo $this->getFieldsByName($ticket, 'video')->value;
} ?>

To make it more safe, checking if both fields are defined before using them, you can do the following:

<?php 
$customFields = $this->getFieldsByName($ticket);

if (($customFields['showVideo'] ?? null) && ($customFields['video'] ?? null) 
  && $customFields['showVideo']->rawvalue == 1) {
    echo $customFields['video']->value;
} ?>

Support staff–only fields

The more one talks to help desk agents and their supervisors the more apparent it becomes that being able to provide an amount of structured information not visible to the client may not just be a good idea but an essential part of being able to run a help desk efficiently or event possibly within regulatory compliance. Collecting and managing this information can be implemented in Akeeba Ticket System creating support staff–only fields.

Let's give an example to make it easier to understand. A travel agency allows its clients to file support tickets to sort out issues before, during or after the guided tour trip they have booked. Because an entire family may be booking a trip it's not possible to have an 1:1 assignment of Joomla users on the company's site and the client account numbers in the company's booking system — the entire family booking a trip would be a single client. A support agent would have to find out which booking reference and client account number in the company's booking system the support case refers to and log it for future reference, either the support agent's future reference as they continue the conversation with the client or a supervisor's when they are reviewing a sample of support cases for the yearly performance evaluation.

At the very least this requires two fields which need to only be able to be filled in by the support agent and only be visible to the support agent: Client Number and Booking Number.

We will assume that support agents are members of the Support Staff user group and that there is an access level called Support Access which only includes the Support Staff user group. We will also assume there are two ATS categories, Pre-Sales Inquiries and After–Sales Care. The fields we create will only be accessible in the After–Sales Care category. Finally, we will need to put them in a Field Group called Booking System Reference.

First we go to Components, Akeeba Ticket System, Field Groups to create our field group. Make sure the drop–down at the top left reads Tickets and click on the New button. Enter the following information:

  • Title: Booking System Reference

  • Description: Cross–reference the client information with the Booking System and enter the respective references in the fields below.

  • Access: Support Access

Click on Save & Close.

Now go to Components, Akeeba Ticket System, Fields. Make sure the drop–down at the top left reads Tickets and click on the New button. Enter the following information:

  • Title: Client Number

  • Type: Text (text)

  • Name: client-number

  • Label: Client Number

  • Required: Yes

  • Default Value: n/a

  • Filter: Text

  • Maximum Length (characters): 15 — we assume the client IDs are a maximum of 15 characters in the company's booking system

  • Field Group: Booking System reference

  • Category: remove the “All” entry and select the “After–Sales Care” category.

  • Access: Support Access

Click on the Options tab and set the following:

  • Editable In: Site

  • Automatic Display: Before Display — we want this information to be displayed in the ticket

Click on the Permissions tab. Select the Support Staff user group. Set the Edit Custom Field Value permissions to Allowed. Click on the drop–down next to Save & Close and select Save & New to start defining the next custom field. Enter the following information:

  • Title: Booking Number

  • Type: Text (text)

  • Name: booking-number

  • Label: Booking Number

  • Required: Yes

  • Default Value: n/a

  • Filter: Text

  • Maximum Length (characters): 30 — we assume the booking IDs are a maximum of 30 characters in the company's booking system

  • Field Group: Booking System reference

  • Category: remove the “All” entry and select the “After–Sales Care” category.

  • Access: Support Access

Click on the Options tab and set the following:

  • Editable In: Site

  • Automatic Display: Before Display — we want this information to be displayed in the ticket

Click on Save & Close.

The client never sees these two fields but the support staff does. The fields are displayed right above the posts in the ticket (i.e. above the conversation).

When a ticket is first submitted these will both display as n/a, hinting the support agent they need to do some work. They can click on the Edit Ticket button to enter this information which presumably they queried in the company's booking system. If the client had not provided enough information they can instead ask them for clarification (“What's your full legal name so I can look you up in our system?”) without editing the ticket at this point.

Once this information is entered the support agent will see it above the conversation, letting them quickly pull up information about the client's booking to better help them.