[Part 2] Using line item subsets for dynamic error messages for user input validation

ryan_kohn
ryan_kohn
in Best Practices

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:

ryan_kohn_1-1658957207665.png

ryan_kohn_2-1658957233790.png

ryan_kohn_3-1658957248411.png

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.

General Tip:
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.

Blueprint:

ryan_kohn_0-1658962025353.png

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.

ryan_kohn_1-1658962104282.png

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.

Blueprint:

ryan_kohn_2-1658962446871.png

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

Blueprint:

ryan_kohn_4-1658962895603.png

I also created a UX page to serve as a reference for end users that want to know more detail about the validation logic.

UX:

ryan_kohn_3-1658962749218.png

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?

Blueprint:

ryan_kohn_5-1658963151544.png

Grid View:

ryan_kohn_7-1658963304406.png

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.

Blueprint:

ryan_kohn_9-1658963653531.png

Grid View (note: L4 Target Adjustment Requests are on pages):

ryan_kohn_8-1658963628363.png

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

Blueprint:

ryan_kohn_10-1658963737907.png

Grid View:

ryan_kohn_11-1658963866506.png

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.

Final UX:

ryan_kohn_17-1658964256184.png

Input grid configuration (conditional formatting):

ryan_kohn_13-1658964104093.png

Input grid configuration (context):

ryan_kohn_1-1658964646734.png

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):

ryan_kohn_14-1658964133284.png

Error grid configuration (filter):

ryan_kohn_15-1658964164915.png

Using the above filter, we are only showing cases where the error exists for the selected item.

Error grid configuration (context):

ryan_kohn_0-1658964587722.png

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.

Conclusion

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: 

  • More detailed error message text (and the ability to update it from the UI and in a deployed model without formula access, so that model admins/power users can do it easily) 
  • Helpful tips for resolution 
  • Additional links to validation rules or resolution ideas 

 

Feel free to post questions, comments, or other examples in the comments section below.

Tagged:

Comments

  • bantiatwork
    bantiatwork

    Really helpful article and very powerful use of multidimensionality, which is core of Anaplan. Handling error has been difficult with Anaplan but this made it very easy.

  • ShubhamCh
    ShubhamCh

    Great work. Beautifully explained. I should try to recreate it in a POC model.

    Thanks @ryan_kohn for this article. 

Categories