Change Filter

Use this Node to process only new or changed keyed values and maintain their comparison baseline.

Revision History

0.0.0.5 - Initial release.
0.0.0.6 - Improved Workflow state sharing between filtering and committing changes.

Setup Notes

You can add this Node to a Workflow without configuring a Connection, authentication, or external access. The Node runs on the CloudRuntime cluster.

Choose a CollectionName for each independent set of values that you want to track. A collection is scoped to the current site environment, so Workflows in the same environment can share its committed comparison baseline.

CollectionName is required and can contain up to 986 characters.

Methods

This Node provides methods for filtering changes, committing successfully processed values, and clearing committed values.

FilterChanges

Returns each item whose Value is new or has changed since it was last committed for the same Key and CollectionName.

The Node compares the serialized Value with the committed baseline. It stages each returned item so that a later CommitChanges Step in the same Workflow activation can commit it.

Parameter	Type	Description
CollectionName	String	The collection used to isolate the committed comparison baseline.
Items	Array	The keyed values to check for changes.
Items.Key	Object	The required stable identity of the item.
Items.Value	Object	The value to compare with the committed baseline. This value can be null.

Return	Type	Description
ChangedItems	Array	The new or changed items, returned in input order.
ChangedItems.Key	Object	The stable identity supplied in Items.Key.
ChangedItems.Value	Object	The new or changed value supplied in Items.Value.

CommitChanges

Commits the staged values for successfully processed items. On a subsequent FilterChanges run, the Node excludes an item when its serialized Value matches the committed value for the same Key and collection.

Parameter	Type	Description
CollectionName	String	The collection used by the corresponding FilterChanges operation.
Items	Array	The successfully processed items whose staged values should become the new baseline.
Items.Key	Object	The required key returned by the corresponding FilterChanges operation.

This method does not return a value.

ClearChanges

Deletes the committed baseline for each supplied Key. The next FilterChanges run treats the corresponding values as new.

Parameter	Type	Description
CollectionName	String	The collection that contains the committed values to clear.
Items	Array	The items whose committed keys should be cleared.
Items.Key	Object	The required key whose committed baseline should be deleted.

This method does not return a value.

Usage Notes

• Use a stable Key for each source record, e.g. its source-system ID. Keep the key's data type and structure consistent between filtering, committing, and clearing.
• Use the same CollectionName in related FilterChanges, CommitChanges, and ClearChanges Steps. Different collection names maintain independent baselines.
• Place CommitChanges after the Steps that process ChangedItems. Pass only the Key values for items that were processed successfully.
• CommitChanges requires FilterChanges to run first with the same collection in the same Workflow activation. Pending changes are not inherited by a Sub Workflow.
• An item is excluded from later runs only after its value has been committed. If processing fails and you do not commit the item, it remains eligible for a later run.
• FilterChanges returns only the first occurrence when the same serialized Key and Value appear more than once in one input stream. It raises an error if the same serialized Key appears with different serialized values.
• Because comparison uses serialized values, changes to a value's data type, structure, property order, or content can cause the item to be returned as changed.
• ClearChanges succeeds when a supplied key has no committed baseline.

Examples

Process only changed customer records

1. Add FilterChanges and set CollectionName to CustomerSync.
2. Map each customer's source ID to Items.Key and the data to compare to Items.Value.
3. Connect ChangedItems to the Steps that create or update customers in the target system.
4. Add CommitChanges after successful processing, set CollectionName to CustomerSync, and pass the successfully processed Key values to Items.
5. Run the Workflow again. FilterChanges excludes customers whose values still match the committed baseline.

To process a customer again regardless of its current value, pass its Key to ClearChanges with the same CollectionName before the next FilterChanges run.