Entity Change Tasks

Generic entity change task for modifying entity custom values, especially useful in "Before" triggers where you need to modify the entity before it's saved.

Entity/Change

Change entity custom values on the currently tracked entity in a Before trigger context.

task: "Entity/Change@1"
name: changeEntity
inputs:
  changes:
    customValues:
      myField: "newValue"
      calculatedField: "{{ computedValue }}"

Inputs

Parameter	Type	Required	Description
changes	object	Yes	Object containing the fields to change
changes.customValues	object	No	Custom field values to set on the entity

Use in Before Triggers

The Entity/Change@1 task is designed primarily for use in Before triggers, where the entity has not yet been persisted. This allows you to modify the entity's data before it's saved to the database.

triggers:
  - type: "Entity"
    entityName: "Order"
    eventType: "Modified"
    position: "Before"

activities:
  - name: enrichOrder
    steps:
      - task: "Entity/Change@1"
        name: setDefaults
        inputs:
          changes:
            customValues:
              lastModifiedBy: "{{ currentUser.name }}"
              modifiedDate: "{{ now() }}"
              region: "{{ parseAddress(Order.ShipToAddress).state }}"

warning

Async "Before" triggers are forbidden. All Before triggers must use executionMode: Sync.

Removing a Custom Value Field

To remove a custom value key from the entity entirely (rather than setting it to null), assign the special sentinel string "$delete" as its value:

task: "Entity/Change@1"
name: clearField
inputs:
  changes:
    customValues:
      obsoleteField: "$delete"

When the system processes the changes, any key whose value is exactly "$delete" is removed from the entity's custom values dictionary. Keys that were not present are silently ignored (no error is thrown).

Sentinel rules

Rule	Detail
Exact match only	The value must be the string $delete — case-sensitive, no leading/trailing spaces, no additional characters. Values like $DELETE, $delete , or $delete extra are treated as ordinary strings and stored as-is.
Top-level keys only	"$delete" nested inside a list or sub-object does not trigger removal. Only a direct string value on a customValues key causes the key to be deleted.
Bypasses overwrite guard	Internally, the merge uses overwriteExisting: false by default to prevent accidental overwrites. The $delete sentinel bypasses this guard because an explicit delete is always intentional — it will remove the key even when overwriteExisting is false.

Combining removals and updates in one task

Removals and new values can be mixed freely in a single Entity/Change@1 step:

task: "Entity/Change@1"
name: restructureFields
inputs:
  changes:
    customValues:
      legacyFlag: "$delete"       # removed
      region: "{{ computedRegion }}"  # set / updated