Field Change Events

In this article:

• Setting Up A Field Monitor
• Trigger Conditions
• Editing or Deleting A Field Monitor

The Field Change Event monitor gives customers the ability to set an option in their Flow Executions that will monitor their data for predefined changes, then set what they would like to happen once that change has been detected.

In this article we will show how to create, edit and remove Field Monitors within your Flow Executions.

Setting Up A Field Monitor

You can set up a Field Monitor by navigating to your Flow Configuration screen.

Next, scroll down to the section labeled Field Change Event or click the link in the lower right sidebar labeled Field Change Event.

Click the button labeled Add Field Monitor.

In the modal that appears enter the information needed to set up this monitor:

Monitor Configuration

Namespace - This is the name of this monitor, in the event you have multiple monitors, this helps identify it from the others

Key Field - This is the field you would like to monitor for changes. This field identifies unique records (e.g., Master Bill, House Bill, Forwarder Reference)

Field To Monitor - This is the field whose value will be monitored for changes or consistency across flow executions (e.g., status, tracking number, carrier)

Trigger Conditions

Trigger When - Choose when you want the monitor to trigger:

• Value Changed - Trigger when the field value changes between executions (default behavior)
• Value Unchanged - Trigger when the field value remains the same across executions

First Occurrence - Check this box if you want to trigger notifications/actions the first time a field is monitored (when going from unset to set). This is useful for:

• Detecting when a new field appears in your data
• Being notified when a record is first processed
• Triggering actions on initial field population

Actions

Action - This field allows you to select the action you would like Chain.io to take once the trigger condition has been met. Customers have the following options to choose from:

• Remove Record - removes the item from the record then continues the flow
• No Action - takes no action at all (useful when you only want notifications)
• Skip Flow - this will initiate a flow status of Skipped and move on to the next execution
• Fail Flow - this will initiate a flow status of Failed

Notifications

Notifier Type - This field allows you to select how you would like to be notified if the trigger condition is met:

• Email - choosing this option will provide an email field for you to enter an email address (or comma-separated list of addresses) that will receive a message if this monitor detects a change
• Webhook - choosing this option will provide fields for you to enter a webhook URL and API key that will receive a response if this monitor detects a change
• Log Message Only - choosing this will send a message to the Flow Execution log that can be viewed in the Flow Execution Details

When you have completed all the fields provided, click Add Field Monitor button to save your Field Change Event Monitor.

You should now see your monitor listed in the Field Change Events panel, organized by namespace.

Example Use Cases

Monitoring for Changes

Use Value Changed trigger to:

• Detect when a shipment status changes
• Monitor carrier updates
• Track reference number modifications
• Alert on date changes

Monitoring for Consistency

Use Value Unchanged trigger to:

• Verify that critical fields remain constant
• Detect stale data that hasn't updated as expected
• Ensure data integrity across multiple executions
• Alert when expected updates don't occur

First Occurrence Monitoring

Enable First Occurrence to:

• Be notified when new shipments appear
• Trigger workflows on initial data population
• Initialize tracking for new records
• Set up initial state for monitoring

Editing or Deleting your Field Change Event Monitor

To edit or delete your Field Change Event Monitor, navigate to the Field Change Event panel in your Flow Configuration.

In the list of Field Monitors within your Namespace:

• Select the Pencil icon to edit the settings of your Field Change Event Monitor
• To delete your monitor, click the Trash Bin icon to remove it

When you delete a monitor, you will be prompted to confirm the deletion as this action cannot be undone.

Technical Details

Field Format

Fields are specified in your log files in the format entity.field_name:

• shipment.master_bill
• shipment.forwarder_reference
• customs_declaration.declaration_number

The system supports monitoring fields on:

• Shipment entities (most common)
• Customs Declaration

How It Works

The Field Monitor uses a cache system to compare values across flow executions:

1. First execution: The monitor stores the current value of the monitored field
2. Subsequent executions: The monitor compares the new value against the stored value
3. Trigger evaluation: Based on your trigger settings (changed/unchanged), the monitor determines if action should be taken
4. Action execution: If triggered, the configured action is performed and notifications are sent
5. Cache update: The new value is stored for the next comparison

The cache uses the format: namespace|key_field_value|monitored_field to uniquely identify each monitored value.

Best Practices

• Use meaningful namespaces to organize multiple monitors
• Choose appropriate key fields that uniquely identify your records
• Test your monitors with sample data before deploying to production
• Use "No Action" initially when setting up new monitors to observe behavior
• Monitor critical fields only to avoid excessive notifications
• Use email notifications sparingly to prevent inbox overflow
• Combine Value Unchanged with First Occurrence to detect when new records appear with expected values