[Part 2] Using line item subsets for dynamic error messages for user input validation
- Step 1: Create a module for your error messages
- Step 2: Create your line item subset
- Step 3: Create a System module to store metadata associated with the validations
- Step 4: Create a module and use COLLECT to summarize error information
- Step 5: Create an Output module to display the error messages and other metadata
- Step 6: Add an output line item to your input module to display the number of errors
- Step 7: Build the User Experience
In Part 1, we walked through various approaches to generating error messages for user input validation, each of which had functional limitations or risk factors for performance and maintainability. In this part, we will talk through how to leverage line item subsets to provide scalable user input validation messages.
We left off in Part 1 with an example that required duplicating similar logic across multiple line items in multiple modules. Compare these examples below:
In each of these examples, we've had to essentially write the exact same formula for each line item while only changing which line item it references. This is a good time to revisit our general tip from Part 1.
Whenever you catch yourself replicating the same formula structure over and over again (e.g. between line items or across conditions in a long, nested IF statement), it's a good indicator that you are trying to solve a multi-dimensional problem without using a multi-dimensional structure. Anaplan is optimized for multi-dimensional calculations, so we want to leverage that structure as much as we can.
With that in mind, let's walk through the steps to set up error messages with line item subsets.
Step 1: Create a module for your error messages
In this module, we will define the logic for each validation rule that can be displayed to the end user.
Dimensions: L4 Target Adjustment Requests (note: this has the same dimensionality of the inputs we are validating)
Line Item formats: Number
Generally speaking, we want to use Booleans instead of Numbers whenever possible (see 2.02-07). However, since line item subsets only work with Number-formatted line items, we can't use Booleans in this case.
For each of my formulas, I will be following the structure of having the validation logic in the condition of an IF statement, and returning 1 for TRUE and 0 for FALSE. My formulas each look like this:
IF <condition> THEN 1 ELSE 0
Note that this module should only contain error messages that you will display to the end user. Do not include any staging line items or calculations in this module. Instead, include them in another Calculation or System module.
Additionally, I will be treating the All Errors line item as the parent of my line item subset, so I will set Is Summary to TRUE.
Step 2: Create your line item subset
Create a new line item subset to point to the module you just created. Be sure to check the Include New Items? box so that you have the flexibility to expand your validation logic in the future without having to manually adjust the line item subset.
Step 3: Create a System module to store metadata associated with the validations
Once the line item subset is created, we can basically treat it like a regular list. We will be creating a System module so that we can have more detailed messages or other information associated with each error message. This gives the flexibility to have the text of an error message be editable by the model administrator.
Dimensions: lis Error Messages
Line Items: Error Message, Detailed Error Message, Link for More Information
I also created a UX page to serve as a reference for end users that want to know more detail about the validation logic.
Step 4: Create a module and use COLLECT to summarize error information
This is the key Calculation module that will leverage the COLLECT capability of line item subsets to pull in detail around which validation rules have been violated for each request.
Dimensions: L4 Target Adjustment Requests, lis Error Messages
Line Items: Error Count, Has Error?
Step 5: Create an Output module to display the error messages and other metadata
This module will be used to display the error messages associated with each target adjustment request. Note that we will be leveraging both hierarchy filters and another filtering, later on, so don't worry if the grid view looks a bit odd at this point!
Dimensions: L4 Target Adjustment Requests, lis Error Messages
Line Items: Message (Applies To: lis Error Messages), More Detail (Applies To: lis Error Messages)
While we normally avoid subsidiary views (see 2.01-06), we will need to use them here in order to allow the Hierarchy filter to work properly on our final UX page.
Grid View (note: L4 Target Adjustment Requests are on pages):
Step 6: Add an output line item to your input module to display the number of errors
This line item can refer directly to the Calculation module used to create the line item subset. This avoids unnecessary daisy chaining (see 2.02-19).
Format: Number; Zero Format: Hyphen
Step 7: Build the User Experience
Now that we have all the building blocks in place, we can put together a UX page to show the error messages.
Input grid configuration (conditional formatting):
Input grid configuration (context):
Be sure to enable the Hierarchy filter for the L4 Target Adjustment Requests list in order to allow the Errors grid to sync.
Error grid configuration (pivot):
Error grid configuration (filter):
Using the above filter, we are only showing cases where the error exists for the selected item.
Error grid configuration (context):
Ensure you enable Sync on Selection in order to allow the user to select a row for which to display the errors. I also normally turn this off for line items and other dimensions in order to make the end user experience more seamless.
There you have it! Leveraging line item subsets is a flexible, scalable, and user-friendly way to show error messages to end users for validating their inputs.
Summary of advantages
- Easy summation of the number of errors associated with a particular row to help people track their progress
- Helpful and informative UI to show all applicable error messages for an entire row
- Scalable for adding new validations (just add it to the line item subset calculation and it will update everywhere downstream, rather than having to add several additional line items every time and adjust complex formulas)
- You can add further metadata to each individual error message without requiring excessive amounts of additional calculation requirements (since you don’t need to calculate at the lowest level anymore)
Examples of supplementary error information:
Feel free to post questions, comments, or other examples in the comments section below.