Requiring a ticket attachment if a particular dropdown option is selected

How to require an attachment in a ticket if a particular dropdown option is selected

We needed to require an attachment if a certain dropdown option was selected by the user when they are filling out a certain form to submit a ticket. Without being able to require the attachment, extra time would need to be spent by the agent to contact the user and ask for the additional document.

Solution Overview

This was done by creating a custom checkbox field that is set to be required, and adding the checkbox to the form, hiding the checkbox via CSS, then programatically selecting or clearing the checkbox according to the dropdown option selected and the number of attachments present.

Limitations

This solution detects that an attachment has been uploaded, but doesn't verify that the attachment is the particular document that needs to be attached.
This solution uses MutationObserver (https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver), which is not supported in some older browser versions
A user could get around the requirement to upload an attachment by using the DOM inspector to show the checkbox, and then selecting it manually.

Steps

Add the custom checkbox field

Create the custom checkbox field

Navigate to Admin > Ticket Fields
Click Add field
Select Checkbox type
Under Permissions, select Editable for end users
Enter whatever title you would like, in Title shown to agents and Title shown to end users. I used the title 'Attachment'
Select the Required to submit a request option.
Click Save to create the field
Note the field ID shown in the list of ticket fields for the new ticket field

Add the custom checkbox field to the form

Navigate to Admin > Ticket Forms
Locate the form for which you need to require the attachment, and click it
Drag the new field from the list of fields on the right to the list of fields in the form. Make sure that it is the last field in the form (because you want the error notification that appears if an attachment is required but not uploaded, to appear above the attachment upload box).
Click Save form to save the change.

Hide the checkbox field

Add the following to style.css to hide the field label and the field (replace the custom field ID in this code with your custom field ID). You have to hide the field label and field individually instead of hiding the <div> that contains them, because if there is an error notification that an attachment wasn't uploaded, it is inside the <div>.

#request_custom_fields_360017775731_label,
#request_custom_fields_360017775731 {
display: none;
}

Set the checkbox according to the attachments and dropdown

1) Determine the field ID of the dropdown. You can do this from Admin > Ticket Fields or with the DOM inspector by opening the form in your Zendesk, and then inspecting the dropdown. The screenshot below shows the dropdown on the web page, and the element inspector portion that shows the field ID

2) Add the following code in script.js inside the document ready function, e.g.after $(document).ready(function () { : and before the ending line }); [You have to adjust the field IDs in attachmentCheckboxField and formDropdownClass to match your field IDs, and adjust the option checked in function isFormAttachmentRequired to match the particular option in your case]:

// Callback function to execute when mutations in form attachments or dropdown are observed: 
// clear or select Attachment checkbox according to dropdown
var mutationObservedForm = function (mutationsList) {
    mutationsList.forEach(function (mutation) {
       if (mutation.type == 'childList') {
           setFormAttachmentCheckbox();
       }
    });
};

// Define some variables for requiring form attachments
var attachmentCheckboxField = 'request_custom_fields_360017775731';
var attachmentCheckboxId = '#' + attachmentCheckboxField;
var attachmentErrorNotification = 'Report must be attached';
var formDropdownClass = '.request_custom_fields_360017548611';
var formObserveMutationOptions = { childList: true, subtree: true };

// Clear or select checkbox according to dropdown and attachments:
// Set Attachment checkbox if no attachments required, or if attachments are required and at least one is uploaded, otherwise clear it
function setFormAttachmentCheckbox() {
    if (isFormAttachmentRequired()) {
        if ($('#request-attachments-pool .upload-item').length) {
            selectCheckbox(attachmentCheckboxId);
        }
        else {
            clearCheckbox(attachmentCheckboxId);
        }
    }
else {
        selectCheckbox(attachmentCheckboxId);
    }
}

// Return true if dropdown option 'ABCD' is selected
function isFormAttachmentRequired() {
    return $(formDropdownClass + ' a.nesty-input').attr('aria-expanded') &&
         $(formDropdownClass + ' a.nesty-input').text() === 'ABCD';
}

// Select checkbox
function selectCheckbox(eltselector) {
    $(eltselector).prop('checked', true);
}

// Clear checkbox
function clearCheckbox(eltselector) {
    $(eltselector).prop('checked', false);
}

// If attachment checkbox field exists, select it,
// and watch for changes to attachments and dropdown
if ($(attachmentCheckboxId).length) {
    selectCheckbox(attachmentCheckboxId);
    startObserveMutations('#request-attachments-pool', formObserveMutationOptions, mutationObservedForm);
    startObserveMutations(formDropdownClass, formObserveMutationOptions, mutationObservedForm);
}

// Adjust attachment error notification
var attachmentErrorElt = $('.' + attachmentCheckboxField + ' .notification-error');
    if (attachmentErrorElt.length) {
    attachmentErrorElt.text(attachmentErrorNotification);
}

Note: The code that detects changes to the attachments and dropdown uses MutationObserver (https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver), as mentioned above. Basically you create an observer instance and pass it a callback function to execute when changes are observed. Then you start the observer, passing it the target node and options specifying what changes to observe.

When the above steps are done, and style.css and script.js are changed as shown above, then you will see that if you open the form and select the dropdown option that requires an attachment, and then click Submit, an error notification is displayed:

Hope this helps somebody!

Karen D Snyder

27. März 2019 19:43

Sorry, I need to make a change in what I wrote above. When you create the custom field, you should not select the option Required to solve a ticket.

Brett - Community Manager

28. März 2019 14:10

Thanks for sharing this Karen :)

This is awesome!

I've also updated your post to remove the Required to solve ticket option.

Cheers!

Jennifer Rowe

28. März 2019 17:25

I love this tip! Thanks so much for sharing it, Karen.

Kevin Witt

17. Oktober 2019 08:02

Great article, but I am having problems with the js. I get the following error in console "startObserveMutations is not defined".

Am I missing something?

Trapta

17. Oktober 2019 08:25

Hi Kevin Witt,

Can you share a bit more detail here? Like the screen shot of the code of the URL of you HC?

Thanks

17. Oktober 2019 09:22

Sure, a configured as per the article (Except I didn't hide the checkbox at this point so I can see what is happening).

I have a drop-down that determines if the attachment is required, with the options "Attachment not required" and "Attachment required".

The error I see in the console is:

The HC is in my sandbox: https://unifydemo1508140682.zendesk.com

The form is called "Attachment Test".

My JS is as follows:

// Callback function to execute when mutations in form attachments or dropdown are observed:
// clear or select Attachment checkbox according to dropdown
var mutationObservedForm = function (mutationsList) {
mutationsList.forEach(function (mutation) {
if (mutation.type == 'childList') {
setFormAttachmentCheckbox();
}
});
};

// Define some variables for requiring form attachments
var attachmentCheckboxField = 'request_custom_fields_360003651537';
var attachmentCheckboxId = '#' + attachmentCheckboxField;
var attachmentErrorNotification = 'Report must be attached';
var formDropdownClass = '.request_custom_fields_360003651357';
var formObserveMutationOptions = { childList: true, subtree: true };

// Clear or select checkbox according to dropdown and attachments:
// Set Attachment checkbox if no attachments required, or if attachments are required and at least one is uploaded, otherwise clear it
function setFormAttachmentCheckbox() {
if (isFormAttachmentRequired()) {
if ($('#request-attachments-pool .upload-item').length) {
selectCheckbox(attachmentCheckboxId);
}
else {
clearCheckbox(attachmentCheckboxId);
}
}
else {
selectCheckbox(attachmentCheckboxId);
}
}

// Return true if dropdown option 'ABCD' is selected
function isFormAttachmentRequired() {
return $(formDropdownClass + ' a.nesty-input').attr('aria-expanded') &&
$(formDropdownClass + ' a.nesty-input').text() === 'Attachment required';
}

// Select checkbox
function selectCheckbox(eltselector) {
$(eltselector).prop('checked', true);
}

// Clear checkbox
function clearCheckbox(eltselector) {
$(eltselector).prop('checked', false);
}

// If attachment checkbox field exists, select it,
// and watch for changes to attachments and dropdown
if ($(attachmentCheckboxId).length) {
selectCheckbox(attachmentCheckboxId);
startObserveMutations('#request-attachments-pool', formObserveMutationOptions, mutationObservedForm);
startObserveMutations(formDropdownClass, formObserveMutationOptions, mutationObservedForm);
}

// Adjust attachment error notification
var attachmentErrorElt = $('.' + attachmentCheckboxField + ' .notification-error');
if (attachmentErrorElt.length) {
attachmentErrorElt.text(attachmentErrorNotification);
}

21. Oktober 2019 14:35
Bearbeitet

Oops, I wrote the post above with the JS to do this, and it looks like I left out the code for the startObserveMutations function! Sorry about that, here it is:

// Function to start observing node for mutations
var startObserveMutations = function (nodeSelector, options, callbackFunction) {
var node = document.querySelector(nodeSelector);
if (node) {
var observer = new MutationObserver(callbackFunction);
observer.observe(node, options);
return observer;
}
};

Hopefully this will fix the problem.

18. Oktober 2019 06:32

Kevin Witt, as Karen D Snyder mentioned, you need to write the startObserveMutations function. Also, looking at your code, you are looking for the changes in the attachment field and in your code you are observing the checkbox for changes.

21. Oktober 2019 08:14

A big thank-you to Karen D Snyder, you saved me allot of time with this.

21. Oktober 2019 14:35

Glad it's working, sorry for leaving out the function in the first place!