Add a validation policy to control configuration data input

Abstract

How to create a custom validation policy to ensure that data input value for an entity property is valid.

The Commerce Engine pre-defines a number of default validation policies in the Plugin.Validation.PolicySet JSON file to validate data input values. You can update the policy set file to add custom validation policies or to modify existing ones to help enforce specific business rules, and ensure data integrity.

Validation policies apply to data entered using the Business Tools interface and to data entered using API requests.

The following procedure shows how to add a new custom validation policy that helps enforce an example of a naming convention for the shopping cart where:

  • A cart name can only contain alphanumeric characters.

  • A cart name must be between 4 and 10 characters in length.

To add a custom validation policy:

  1. On the Commerce Engine service instance, open the wwwroot\data\Environments\Plugin.Validation.PolicySet-1.0.0.json file.

  2. Go to the bottom of the file, and add the policy shown in the following sample, where:

    • The "TypeFullName" corresponds to the namespace of the Cart entity class that defines the property value to validate.

    • The "Name" property is the name of the entity property value to validate, in this case the cart "Name" property.

    • The "MinLength" property enforces a minimum number of characters required for the "Name" value to be valid.

    • The "MaxLength" property enforces a maximum number of characters allowed for the "Name" value to be valid.

    • The "RegexValidator" property defines a regular expression allowing alphanumeric characters only.

    • The "RegexValidatorErrorCode" value refers to the Commerce Term, where the error message is defined.

    {
        "$type": "Sitecore.Commerce.Core.ValidationPolicy, Sitecore.Commerce.Core",
        "TypeFullName": "Sitecore.Commerce.Plugin.Carts.Cart",,
        "Models": {
          "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Core.Model, Sitecore.Commerce.Core]], mscorlib",
          "$values": [
            {
              "$type": "Sitecore.Commerce.Core.ValidationAttributes, Sitecore.Commerce.Core",
              "Name": "Name",
              "MinLength": 4,
              "MaxLength": 10,
              "RegexValidator": "^[\\w\\s]*$",
              "RegexValidatorErrorCode": "AlphanumericOnly_NameValidationError"
            }
          ]
        }
      }
    
  3. Bootstrap the Commerce Engine.

    Note

    When bootstrapping is completed, you can use send a Get Environment sample request, and then verify that your changes are included in the returned response.

  4. Optionally, to confirm that the Commerce Engine returns the expected error message, you can send an invalid Postman request. In the Add Mira Laptop sample request, change the "CartId" input value to include an invalid character, for example "Cart01!", where the exclamation mark is rejected by the regex validator.

    In the returned response, the "Messages" section contains the following error message:

     "Messages": [
            {
                "MessageDate": "2021-07-28T15:15:00.7992017Z",
                "Code": "ValidationError",
                "Text": "Only alphanumeric characters are allowed in the Name.",
                "CommerceTermKey": "AlphanumericOnly_NameValidationError"
            },
            {
                "MessageDate": "2021-07-28T15:15:00.803528Z",
                "Code": "Warning",
                "Text": "Transaction failed and rolled back.",
                "CommerceTermKey": "TransactionError"
            }

    Note

    Alternatively, you can check the Commerce Engine log file located in the \wwwroot\CommerceEngineServic>\wwwroot\logs folder.