How To Validate NHS Numbers In Model-Driven App Forms! [Solution Sunday #1]

Hi guys, kicking off this series of Solution Sunday, I want to give you a pretty cool script that not only ensures NHS numbers are being formatted correctly (XXX-XXX-XXXX), but are also valid NHS numbers to begin with. To put it quite simply, NHS numbers are generated and validated with a 10 digit format, with the final digit being an error detecting checksum.

For an example of how the checksum is calculated for NHS Numbers, please see the following Wikipedia link here and navigate to the "Format, number ranges, and check characters" section.

So let's get started!

Step 1 - Understand and copy the code

For starters, it would help to understand what the code below is doing before copying and pasting it just yet.

Understand the code

To begin, the code creates a function called validateNHSNumber, which will do a few things.

1. Firstly, it will get the logical name of the NHS Column on the form you're trying to validate it on.
2. It will then condition some error-handling in case the NHS Number is not present, and then retrieve the current value of the NHS Number from the form, so that it can be validated on.
3. If the NHS number is empty, it will clear any existing error messages and exit the function.
4. It will then complete the first layer of validation, ensuring the number is 10 digits and includes the dashes in the correct places (XXX-XXX-XXXX).
5. The code will then remove the dashes to complete the checksum calculation in the background.
6. It will then complete the checksum calculation using the isValidChecksum function which has been created at the bottom of the code.
7. If the validation passes these two layers, the user will be able to submit the number in the form.

function validateNHSNumber(executionContext) {
    var formContext = executionContext.getFormContext();
    // Retrieve the 'ttd_nhsnumber' attribute from the form to perform validation.
    var nhsNumberAttribute = formContext.getAttribute("ttd_nhsnumber");

    // If the NHS number attribute is not present, log an error and exit.
    if (!nhsNumberAttribute) {
        console.error("NHS number attribute is not found on the form.");
        return;
    }

    // Retrieve the current value of the NHS number from the form.
    var nhsNumber = nhsNumberAttribute.getValue();

    // If the NHS number field is empty, clear any existing error messages and exit the function.
    if (!nhsNumber) {
        formContext.getControl("ttd_nhsnumber").clearNotification();
        return true; // No validation error
    }

    // Check if the input includes dashes and is in the correct format "XXX-XXX-XXXX"
    if (!/^\d{3}-\d{3}-\d{4}$/.test(nhsNumber)) {
        // Display error if format is incorrect
        showErrorMessage(formContext, "The NHS number must be in the format 485-777-3456 with dashes.");
        return false;
    }

    // Remove dashes for checksum calculation to validate the numerical part.
    var normalizedNHSNumber = nhsNumber.replace(/-/g, '');

    // Ensure the number is exactly 10 digits after removing dashes.
    if (normalizedNHSNumber.length !== 10 || isNaN(normalizedNHSNumber)) {
        showErrorMessage(formContext, "Please enter a valid 10-digit NHS number.");
        return false;
    }

    // Calculate and validate the checksum.
    if (!isValidChecksum(normalizedNHSNumber)) {
        showErrorMessage(formContext, "The NHS number is not valid. Please check and try again.");
        return false;
    }

    // If all checks are passed, clear any error messages.
    formContext.getControl("ttd_nhsnumber").clearNotification();
    return true;
}

function isValidChecksum(nhsNumber) {
    // Multipliers for the Modulus 11 checksum calculation.
    var multipliers = [10, 9, 8, 7, 6, 5, 4, 3, 2];
    var sum = 0;

    // Calculate the weighted sum for the first 9 digits.
    for (var i = 0; i < multipliers.length; i++) {
        sum += parseInt(nhsNumber.charAt(i), 10) * multipliers[i];
    }

    // Compute the checksum. A valid number has a checksum digit that matches the last digit.
    var checksum = (11 - (sum % 11)) % 11;
    if (checksum === 10) return false; // Checksum of 10 is not used, indicates an error.
    return checksum === parseInt(nhsNumber.charAt(9), 10); // Compare checksum with the last digit.
}

function showErrorMessage(formContext, message) {
    // Display the specified error message on the NHS number field.
    formContext.getControl("ttd_nhsnumber").setNotification(message);
}        

This code currently only supports string columns!

Copy the code

When you copy the code and save it on your machine as a JavaScript file, only one change needs to be made. You must change "ttd_nhsnumber" to the logical name of your NHS Number column that you want validation against.

If this step is missed, the code will throw back an error as it will be trying to validate on a column that doesn't exist (unless your column name is ttd_nhsnumber).

Step 2 - Apply the code to your form

In this second step, you will apply the code to your form.

1. Firstly, import the custom code into your Power Platform Solution. To do this, open your solution and select "+ New", "More", "Web resource" as seen in the below image.

2. You should then see this dialog pop-up show. Select "Choose file" and choose the JavaScript file on your machine containing the code. Give it a display and logical name you'll recognise, with the "Type" set to JavaScript (JS). You can then save this web resource which will make it accessible within your solution.

3. Once this is done, open up your form that includes the NHS Number column. Use the navigation to open up "Form libraries" and "+ Add Library". This will then open up a search box in which you can look up your NHS Number solution and add it as a library. Once this is done, move onto the next step.

4. Next, select the NHS Number field on your form [1] , navigate to Events [2], and select "+ Event Handler" [3].

5. Once this is done you should see the popup [4]. Select your NHS Number Validation Library, and copy the function and following details as such in the below image.

6. Now you can save and publish your form, and give it a test.