Validation Functions

Validation Functions allow us to write conditional logic about whether a property is “valid” based on the current state of an entity or its related entities.

Writing Validation Functions¶

Validation Functions are currently ONLY being evaluated on the Plan Placeholder, Item, and Project Item entities.

Available Inputs¶

Plan Placeholder¶

Input Variables Available Context Notes

obj

{
  ...[plan-placeholder properties]

  itemFamily: {
    ...[item properties]

    projectItem: {
     ...[project-item properties]
    }
  },
  itemOption: {
    ...[item properties]

    projectItem: {
     ...[project-item properties]
    }
  },
  itemType: {
   id: string,
   typePath: string,
   label: string,
   slug: string,
   parentId: string,
   typeRootId: string
  },
}

context

{
  assortment: {
   ...[assortment properties]
  }
}

assortment is the Target Assortment of the Plan.

Item¶

Input Variables	Available Context	Notes
`obj`	`{ ...[item properties] roles: Array<'family' \| 'option' \| ...> }`	`roles` is a system property used to determine if an item is “option” or a “family”.
`context`	N/A	`context` is not accessible here like it is for Formulas.

Project Item¶

Input Variables	Available Context	Notes
`obj`	`{ ...[project-item properties] itemId: string, roles: Array<'family' \| 'option' \| ...>, }`	`obj.item` is not accessible on the Project Item entity like it is for Formulas.
`context`	N/A	`context` is not accessible here like it is for Formulas.

Output¶

The expected output of a validation function is an array of objects with the following structure:

Array<{ message: string, type: 'ERROR' | 'WARNING' }>

Warning¶

A type of 'WARNING' will display an alert message in the Plan.

Error¶

A type of 'ERROR' will prevent the update from being saved.

Examples¶

const validations = [];

if (obj.isDisabled) {
 validations.push({ message: 'Entity is disabled.', type: 'WARNING' });
}

//object reference properties are accessible
if (obj.objectReference1?.colorName === 'BLUE') {
 validations.push({ message: 'Color "BLUE" is not allowed.', type: 'WARNING' });
}

if (obj.isInErrorState) {
 validations.push({ message: 'Illegal state', type: 'ERROR' });
}

return validations;

When Validations Are Processed¶

In Plan¶

Plan Placeholder validation functions run in the Plan:

On load of a Plan.
- Plan Placeholder validations are run on all rows.
On cell edit.
- Plan Placeholder validations run for the modified row(s).

In Boards Property Editor¶

Item and Project Item validation functions run in the Property Editor in Boards:

On Property Editor open.
On property update in Property Editor.

Item validation functions run in the Item Modal:

On Item Modal open.
- Item validations run for every Item Property on the entity.
On Item update.
- Item validations run for every Item Property on the entity.

On Publish (API)¶

On publish, all Plan Placeholder validation functions run for every row of the Plan. If any validation warnings or errors exist, the Publish fails.

Neither Item nor Project Item validation functions run on Publish.

Existing Gaps in Validation Functions¶

Validation Functions Are Not Run On Create or Update Operations Server Side¶

An entity, such as an Item, can be edited outside of one of the apps (e.g. with an API request), which results in an ERROR validation state. This state should not be saved, but because we do not run validations server-side, it is saved.

In Plan, Item or Project Item Validations Are Not Run On Cell Edit¶

Outside of the Item modal, the plan depends entirely on the Plan Placeholder Validation Functions for evaluating warnings and errors.

If Item and Plan Placeholder Validations have different outputs, an update operation could be blocked in one location, but not the other

Plan Cell Edit.
- Plan Placeholder Validation Function returns [] (no validation alerts).
- Update is allowed and no alerts are displayed.
Plan/Boards/Showcase Item Modal.
- Item Validation Function returns ERROR validation alert.
- Update is blocked.

In Boards and Item Modals (all apps), edits are blocked which results in ANY validation (`WARNING` or `ERROR`), in Plan cell editing, only `ERROR` validations are blocked from being saved.¶

Editing Items and Project Items in Boards is a relatively newly introduced functionality. It's not yet defined how alerts will be displayed in Boards, currently any edit results in a validation ERROR or WARNING in Boards is blocked from being saved.