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.