Practical UIB Examples: Prevent Record Submission without Attachments

[Marc Mouries]

Introduction

In many business scenarios, it's crucial to ensure that records submitted through a form have all the necessary attachments. This can prevent incomplete or invalid submissions that might lead to delays and additional follow-up work. 

There are two common variations of this requirement:

1. Specific Categories of Files: Some forms may require specific categories of files to be attached before submission. For instance, a Travel Expense form might need a receipt for airfare and another for lodging. In such cases, dedicated properties should be used to store each attachment instead of using the attachment component. You would add two fields of type File Attachment and make them mandatory.

2. At Least One File Attached: In other scenarios, the form only needs to ensure that at least one file is attached, and the type of file does not matter.

This article presents a way to support the second scenario, ensuring that a record has at least one attachment before submission. Here’s how to achieve this in ServiceNow UI Builder.

Step-by-Step Guide

Overview

To address this need, we'll use the events triggered by the attachment component whenever users add or remove an attachment. These events will help us keep track of the number of files attached, and we will use this information to control whether the submit button is enabled or disabled. Essentially, we'll enable the submit button whenever at least one file is attached.

Step 1: Set Up the page

Set up a page with the following components:

1. A form component
2. A attachment component
3. And a submit button

.

 

Step 2: Configure Client State Parameters

To manage the state of the submit button, you'll need client state parameters that will be updated based on the attachment events.

1. Add the hasAttachments Client State Parameter:

   • Go to the "Client State Parameters" section in UI Builder.
   • Add a new client state parameter named hasAttachments and set its initial value to false.

2. Add the attachmentCount Client State Parameter:

   • Go to the "Client State Parameters" section in UI Builder.
   • Add another client state parameter named attachmentCount and set its initial value to 0.

Step 3: Map Events to Scripts

We'll now create scripts that update the client state parameters based on the attachment events, and then map these events to the scripts.

1. Create a Client Script for "Attachment upload succeeded":

   • In the script editor, write a script to update the client state parameter attachmentCount and set hasAttachments to true if there is at least one attachment. Here is the script:

   • Name: Handle Attachment upload

   • Script:
     

     function handler({api, event, helpers, imports}) {
         const newCount = api.state.attachmentCount + 1;
         api.setState('attachmentCount', newCount);
         api.setState('hasAttachments', newCount > 0);
     }​

2. Create a Client Script for "Attachment delete succeeded":
   • Write a script to decrement the attachmentCount and update hasAttachments accordingly.
   • Name: Handle Attachment Delete
   • Script:
     

     function handler({api, event, helpers, imports}) {
         const newCount = api.state.attachmentCount - 1;
         api.setState('attachmentCount', newCount);
         api.setState('hasAttachments', newCount > 0);
     }​

3. Map the "Attachment upload succeeded" Event:
   1. Select the attachment component.
   2. Go to the "Events" section.
   3. Click on " + Add event mapping"
   4. Find the Attachment upload succeeded event.
   5. Map this event to the Handle Attachment Upload client script.
   6. Click Add.

4. Map the "Attachment delete succeeded" Event:

   • Similarly, find the Attachment delete succeeded event in the attachment component.
   • Map this event to the Handle Attachment Delete client script.
   • Click Add.

Step 3: Map Events to Scripts

Step 4: Bind the State Parameter to the Submit Button

Finally, we'll bind the client state parameter to the disabled property of the submit button to ensure it is only enabled when there are attachments.

1. Select the Submit Button Component
2. Go to the properties panel.
3. Find the disabled property.
4. Click the Bind icon
5. Select script and set the script to return true if there are no attachments, effectively disabling the submit button, and false otherwise. Here is the simple script:
   

   function evaluateProperty({api, helpers}) {
   	return ! api.state.hasAttachments;
   }​

6. Click Apply.

Step 5: Test Your Configuration

See that it's working as expected.

1. Open the page: Notice that the submit button is disabled by default
2. Upload an Attachment: See how the submit button becomes enabled when an attachment is uploaded.

By following these steps, you can effectively manage the attachment requirement before allowing the submission of a record in the ServiceNow UI Builder workspace. This ensures that users cannot submit records without adding the necessary attachments.

I hope this article was helpful and inspires you to create an even better user experience. With these techniques, you can enhance your forms to ensure they meet all necessary requirements before submission.

[Rohit Motiani]

Thank you Marc for sharing this solution! I believe we can use this in the Catalog submission form as well!!

[Liyakhat]

@Marc Mouries 

Thanks for this article it was helpful, how can we configure event if attachments are added from side bar component i dont find the event attachment upload succeeded

[Marc Mouries]

@Liyakhat  can you share a screenshot of your screen? As you can see below in my workspace i can select the attachment tab item and select the Attachment upload succeeded event.

[SundaramR]

@Marc Mouries Thanks for the post. When form load with attachment already added, How to get the existing attachment count?

[Marc Mouries]

@SundaramR please create a new question and elaborate about the use case