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.

Labels:

• Getting Started : Next Experience
• UI Builder : Next Experience