Formulas

Formulas allow you to programmatically set a property’s value based on the current state of an entity or its related entities.

Writing Formulas¶

Depending on the Entity Type and the Property Type, the expected inputs and output of a formula can vary.

Inputs¶

All Entities¶

Input Variables	Available Context	Notes
`obj`	`{ ...[entityproperties] }`
`context`	`{ previousObj: { ...[state of the obj prior to the update operation] } }`	`previousObj` is sometimes null because there is no previous state. For example, on entity Create. `previousObj` is sometimes the same as obj because no changes have been made (e.g. an empty update is performed).

Object Reference Hydration¶

All Object References properties defined on a Type are expanded and visible to the formula code 1-level deep.

Examples¶

✅ obj.objRefProperty1

❌ obj.objRefProperty1.objRefProperty2

Item¶

Input Variables	Available Context	Notes
`obj`	`{ ...[entity properties] roles: Array<'family' \| 'option' \| ...> }`	`roles` is a system property used to determine if an Item is “option” or a “family”.
`context`	`{ previousObj: { ...[state of the obj prior to the update operation] } }`

Running Formulas on Leveled Items (Option vs Family)¶

Formulas run for family-level properties on both option and Family Items.

Option Items include family-level property data.

Formulas for option-level properties only run on Option Items.

Family Items do not include option-level property data.

It is not possible to access the Item Family object in a formula for an Item Option.

Examples¶

Accessing Item Role (Family vs Option)¶

if (obj.roles.includes('option')) {
    return "this is an option item";
}
if (obj.roles.includes('family')) {
        return "this is a family item"; 
}
return "error - this item has no role";

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]
  },
  previousObj: {
    ...[state of the obj prior to the update operation]
  }
}

assortment is the Target Assortment of the Plan.
previousObj will include a hydrated itemOption and itemFamily. Changes to these hydrated objects will be reflected in obj.

Examples¶

Writing a Plan Placeholder Formula Which Runs on the Correct Item¶

//family level properties
const item = obj.itemFamily;
...

//option level properties
const item = obj.itemOption;
...

//all level properties — run on item option if available, or else run on item family
const item = obj.itemOption || obj.itemFamily;
...

Project Item¶

Input Variables Available Context Notes

obj

{
  ...[project-item properties],

  item: {
    ...[item properties]
  },
  roles: Array<'family' | 'option' | ...>
}

context

{
  project: {
    ...[project properties]
  },
  previousObj: {
    ...[state of the obj prior to the update operation]
  }
}

project is the Project which the Project Item belongs to.

Assorment Item¶

Input Variables	Available Context	Notes
`obj`	`{ ...[assortment-item properties], item: { ...[item properties] } }`	`item` is a reference to the `itemOption` if it exists, otherwise the `itemFamily`. The Assortment Item properties `itemOption` and `itemFamily` are not accessible on the obj.
`context`	`assortment: { ...[assortment properties] } }`	`assortment` is the Assortment which the Assortment Item belongs to.

Output¶

The output of the Formula should match the Property Type.

For example:

If the Property Type is "number", then the formula should return a numeric value.
- A formula does not need to consider the format.
If the Property Type is "text", then the formula should return a string.
If the Property Type is "date", then the formula should return an ISO string.
- Example: return new Date().toISOstring()

When Formulas Are Processed¶

Formulas run in a variety of scenarios depending on the Entity Type and operation being performed.

On Entity Update and Create¶

For all entities, formulas run on Create and Update operations. For example, if an Item is updated, all formulas will run for all properties on the Item object.

In the Plan App¶

The Plan Placeholder serves as a temporary state of data, meaning the values it shows in the Plan are not necessarily saved in our database. Because of this, formulas run on this entity more frequently, and without needing a Create or Update operation to occur.

Data Management in Plan¶

To better understand how this works you must first to understand how the Plan manages row-level data. Let's say you have the following org configuration:

Entity	Property	Property Level
Plan Placeholder, Item	`itemFamilyText`	Family
Plan Placeholder, Item	`itemOptionText`	Option
Plan Placeholder, Project Item	`projectFamilyText`	Family
Plan Placeholder, Project Item	`projectOptionText`	Option
Plan Placeholder, Assortment Item	`assortmentText`	N/A

The Plan uses this configuration to then display the following data: plan-example

In this example, only the placeholder cells highlighted in orange will have Plan Placeholder formulas applied and processed. All other cells will use the Item or Project Item property formulas and will only run on entity update (i.e. cell edit).

When Plan Placeholder Formulas Run¶

Plan Placeholder formulas run on Plan Placeholder cells (highlighted in orange above) in any of the following scenarios:

On load of a Plan.
- Plan Placeholder formulas are run on all Plan Placeholder cells.
Update / Create of Plan Placeholder.
- Formulas are run for the updated/created Plan Placeholder.
Update on ANY cell in a Plan.
- Formulas are run on the modified row(s) for all Plan Placeholder cells.

On Plan Publish¶

When you Publish a Plan, the following formulas run:

All Item formulas are run for all Item Family and Item Option references in the Plan.
All Project Item formulas are run for all Item Family Project Item and Item Option Project Item references in the Plan.
All Assortment Item formulas are run for all Assortment Items in the published Assortment.