Overview
In this tutorial, you will customize your Checklist Component to go from static to data driven. Instead of hard coding items you'll load records from the incident table, transform them with a client script, and bind Edit and Save events to client state so users can add, remove, and update the checklist items.
This guide assumes you are meeting these environment requirements:
Family Release:
YokohamaUI Builder Release: 26.2.59
Roles Required: admin
Prerequisites: Checklist - Basic configuration
Step 1. Open the previously created Checklist Configurations Workspace
- Log in to your ServiceNow instance.
- Navigate to Now Experience Framework > UI Builder in the filter navigator to open the UI Builder interface.
3. Click on the Experiences tab
4. Underneath the Experiences tab, select the 'Checklist Configurations' experience
5. Select 'Default' underneath the 'My Checklist' page
The Checklist Configurations Experience will now open to our previously created Checklist component.
Step 2: Dynamically Load Data from a Table
To populate the checklist dynamically from your tables instead of hardcoding items, add Look up multiple records data resource.
- In the bottom left, under Data and scripts > Data resources > Add data resource
- Select Look up multiple records
- Select Add
- The window to edit the data resource will open.
Update the following:
When to evaluate this data resource: Immediately
Table: Incident
Return fields: Number, Short description, Order
Max results: 10
Return field metadata: checked
5. Close the window
6. Now we will create a Client Script to do some heavy lifting for us.
7. In the bottom left corner, under Data and scripts > Client scripts, click the + button to add a new client script.
8. Name the client script 'On data fetch succeeded' then add the following script:
function handler({ api, event, helpers, imports }) {
const clData = [];
api.data.look_up_multiple_records_1.results.forEach((incident, index) => {
const clItem = {
itemId: incident.number.value,
label: incident.short_description.displayValue,
checked: false,
order: index * 10 // Keep orders in multiples of 10 as it will help in reordering scenario
};
clData.push(clItem);
});
api.setState("checklistData", [...clData]);
}This script converts your backend table data into a format compatible with your Checklist component.
9. In the bottom left, under Data and scripts > Data resources, select Look up multiple records 1.
10. Open the Events tab
11. Select Add event mapping
12. Select Data Fetch Succeeded
13. Select Continue
14. Under Client Scripts, select On data fetch succeeded
15. Select Continue
16. Close the pop-up window
Step 3: Allowing Users to Edit the Checklist
To enable editing of checklist items proceed with the following setup:
- With the Checklist component selected, navigate to the Component configuration panel on the right > Configure > Data and display > Allow editing > True
2. In the left panel > Data and Scripts > select Client state parameters
3. Click +Add to create a new client state parameter
4. Update like so:
Name: isEditMode
Type: Boolean
Initial value: false
5. Select Apply
6. With the Checklist component selected, go to the Component configuration panel on the right > Configure > Data and display > hover over Allow editing until the stacked circles (bind icon) appear > select the bind icon
7. In the Data types tab > Client states > select isEditMode pill > click the small arrow to move it to the top
8. Select Apply
Step 4: Configure Edit Mode
- With the Checklist component selected, go to Events > Add event mapping
- Select Edit clicked
- Select Continue
- Select Set client state parameter
5. Select Continue
6. Choose isEditMode under Client State Parameter Name
7. Set Value to use after triggering event to true
8. Select Add
Now repeat steps 4.1–4.8 for the Edit canceled event:
- Select Add event mapping
- Select Edit canceled
- Select Continue
- Select Set client state parameter
- Select Continue
- Select isEditMode under Client State Parameter Name
- Set value to false
- Select Add
This gives the Checklist’s Edit mode the toggle functionality we needed.
Step 5: Saving User Changes
- Create a client script
Save clickedto save and persist user edits to checklist data: - Click the + next to Client Scripts to add a new script
- Set the script name to Save clicked
- Add the following client script:
function handler({api, event, helpers, imports}) {
const checklistDataBeforeSave = [...api.state.checklistData]; // Optional Backup
let clData = [...api.state.checklistData];
if (!Array.isArray(event.payload)) { // in case of 'editedList'
clData = event.payload.data;
} else {
event.payload.forEach(element => {
switch (element.actionType) {
case 'addedItem':
clData.push(element.data);
break;
case 'removedItem':
clData = clData.filter(e => e.itemId !== element.data.itemId);
break;
case 'editedItem':
clData[clData.findIndex(e => e.itemId === element.data.itemId)] = element.data;
break;
}
});
}
api.setState("checklistData", clData);
api.setState("isEditMode", false);
// Optional: Persist these changes to backend
// You can optimize by comparing before/after and only updating changed records.
}5. Select Apply
For clarification:
- This script ensures changes (additions, deletions, edits) made by users are captured in the client state.
- Further backend logic can be added to persist data.
Now bind this script to the Checklist’s Save clicked event:
6. With the Checklist component selected, go to Events > Add event mapping
7. Select the Save clicked event
8. Select Continue
9. Under Client Scripts, select Save clicked
10. Select Continue
11. Select Add
Troubleshooting
No items appearing? Ensure UI Builder Cache, Environment Cache and Browser cache are cleared.
Edit toggle not working? Verify Allow editing is bound to
isEditMode and that the events are properly mapped.Save doesn't work? Confirm the Save clicked event is mapped to the Save clicked client script and debug as necessary.
Conclusion
Good job! We have turned a static component into a data-driven component with logic to dynamically create check boxes on the fly with our own state management. To continue building, try implementing security and governance (read/write ACLs), add filters to minimize data retrieval, and implement validation to prevent duplicates. With these pieces in place, you’ve built a clean and maintainable foundation for your checklist. Keep going!
