Concepts

Events & Synchronization

Understanding work order events that trigger connector synchronization and how to configure event-based data flows.

Event-Driven Architecture

When work orders change in Field Nation, events trigger outbound synchronization to external systems. When external records change, webhooks trigger inbound synchronization to Field Nation.

Loading diagram...

Available Events

Field Nation publishes events for key work order lifecycle milestones. Configure which events trigger synchronization for each connector.

Work Order Creation & Status

Prop

Type

Description

FN_WO_CREATED?event

Work order first created (may skip draft and go directly to published/routed)

FN_WO_DRAFT?event

Work order set to draft status after creation

FN_WO_PUBLISHED?event

Work order published and made available to providers

FN_WO_APPROVED?event

Work order approved and ready for execution

FN_WO_DELETED?event

Work order soft-deleted (set to delete status)

Provider Assignment

Prop

Type

Description

FN_WO_ROUTED?event

Work order routed to a provider (fires per provider - routing to 10 providers = 10 events)

FN_WO_STATUS_ROUTED?event

Work order status changed to routed (fires once regardless of provider count)

FN_WO_ASSIGNED?event

Work order assigned to provider (via routing acceptance or direct assignment)

FN_WO_CONFIRMED?event

Assigned provider confirmed acceptance

FN_WO_DECLINED?event

Provider declined work order (fires per decline)

FN_WO_UNDECLINED?event

Provider removed decline status

Work Execution

Prop

Type

Description

FN_WO_ON_MY_WAY?event

Provider marked status as 'on my way' to site

FN_WO_PROVIDER_CHECKED_IN?event

Provider checked in (fires per check-in if multiple)

FN_WO_PROVIDER_CHECKED_OUT?event

Provider checked out (fires per check-out if multiple)

FN_WO_TASK_COMPLETED?event

Individual task within work order completed

FN_WO_DONE?event

Provider marked entire work order as completed

Schedule & Timeline

Prop

Type

Description

FN_WO_SCHEDULE_UPDATED?event

Schedule modified (date, time, or duration changed)

FN_WO_DELAYED?event

Work order delayed (typically on-hold status)

FN_WO_POSTPONED?event

Work order postponed indefinitely

FN_WO_AT_RISK?event

System detected work order at risk of not completing on time

Updates & Changes

Prop

Type

Description

FN_WO_UPDATED?event

Basic work order information changed (title, description, core fields)

FN_WO_CUSTOM_FIELD_VALUE_UPDATED?event

Any custom field value updated

FN_WO_SHIPMENT_UPDATED?event

Shipment information modified

FN_WO_INTEGRATION_STATUS_UPDATED?event

Integration-specific status field changed

FN_WO_ALERTS_SENT?event

Alert notifications sent for work order

Messages & Communication

Prop

Type

Description

FN_WO_MESSAGE_ADDED?event

New message added to work order thread

FN_WO_TASK_MESSAGE_ADDED?event

Message added to specific task within work order

FN_WO_CLOSE_OUT_ADDED?event

Close-out information or notes added

Financial Events

Prop

Type

Description

FN_WO_PAYMENT_APPROVED?event

Payment for work order approved

FN_WO_EXPENSE_ADDED?event

Expense item added to work order

FN_WO_COUNTER_OFFER?event

Provider submitted counter-offer for payment terms

Additional Events

Prop

Type

Description

FN_WO_ATTACHMENT_ADDED?event

File or attachment added to work order

FN_WO_CANCELLED?event

Work order cancelled

FN_WO_PENDING_QUALIFICATIONS?event

Work order has pending qualification requirements

FN_WO_PROBLEM_REPORTED?event

Issue or problem reported on work order

Configuring Event Triggers

Selecting Events

In the Integration Broker UI, configure which events trigger synchronization:

Navigate to Event Configuration

Go to your connector settings → Event Triggers section

Select Events

Check the events you want to trigger outbound sync:

✅ FN_WO_ASSIGNED - Sync when provider assigned
✅ FN_WO_DONE - Sync when work completed
✅ FN_WO_APPROVED - Sync when work approved

Configure Action

For each event, specify the action:

Update Record - Update existing external record
Create Record - Create new external record (typically for messages/notes)
Custom Script - Run platform-specific logic

Save Configuration

Test event triggers with sample work orders

Common Event Configurations

Minimal Sync (Status Only)

FN_WO_ASSIGNED - Provider assigned
FN_WO_DONE - Work completed
FN_WO_APPROVED - Work approved

Standard Sync (Status + Communication)

All minimal sync events
FN_WO_MESSAGE_ADDED - Sync messages
FN_WO_SCHEDULE_UPDATED - Sync schedule changes
FN_WO_CUSTOM_FIELD_VALUE_UPDATED - Sync custom fields

Comprehensive Sync (Full Lifecycle)

All standard sync events
FN_WO_ON_MY_WAY - Provider en route
FN_WO_PROVIDER_CHECKED_IN - Check-in tracking
FN_WO_PROVIDER_CHECKED_OUT - Check-out tracking
FN_WO_PAYMENT_APPROVED - Financial tracking
FN_WO_ATTACHMENT_ADDED - Document sync

Synchronization Patterns

Inbound: External System → Field Nation

External systems trigger synchronization via webhooks:

Loading diagram...

Triggers:

Record created in external system
Record status changed
Record field updated (specific fields)
Manual "Sync to Field Nation" button

Outbound: Field Nation → External System

Field Nation events trigger synchronization:

Loading diagram...

Triggers:

Configured Field Nation events
Status changes
Custom field updates
Message additions

Event Payloads

Events include complete work order context:

{
  "event_type": "FN_WO_ASSIGNED",
  "event_timestamp": "2025-01-15T14:30:00Z",
  "workorder": {
    "id": 12345678,
    "title": "On-site Network Installation",
    "status": {
      "id": 2,
      "name": "assigned"
    },
    "assignee": {
      "user": {
        "id": 987654,
        "first_name": "John",
        "last_name": "Technician",
        "email": "john@example.com",
        "phone": "+1-555-0100"
      }
    },
    "schedule": {
      "service_window": {
        "start": {
          "utc": "2025-01-20 09:00:00"
        },
        "end": {
          "utc": "2025-01-20 12:00:00"
        }
      }
    },
    "pay": {
      "type": "fixed",
      "amount": 250.00
    },
    "custom_fields": [ /* ... */ ]
  },
  "correlation_id": "ext-record-456"
}

Best Practices

Event Selection

Synchronization Strategy

Bidirectional Consistency

Map statuses bidirectionally (FN → External and External → FN)
Use correlation IDs to track related records
Handle sync conflicts (last-write-wins or manual resolution)

Idempotency

Ensure same event processed multiple times produces same result
Check correlation ID before creating new records
Use upsert logic (create if not exists, update if exists)

Error Handling

Configure retries for temporary failures
Set up dead letter queue monitoring
Alert on persistent sync failures

Monitoring Event Sync

Integration Logs

Track event processing in Integration Broker logs:

Event received timestamp
Field mappings applied
API call made to external system
Success/failure status
Error details (if failed)

Health Metrics

Monitor key indicators:

Event Processing Rate: Events/minute
Success Rate: % successful syncs
Average Latency: Time from event to external update
Error Rate: % failed syncs
Queue Depth: Pending events in queue

Troubleshooting Events

Complete troubleshooting guide →

Last updated on

Custom Actions with JSONNET

Write advanced data transformation logic using JSONNET for complex field mapping scenarios.

Troubleshooting

Common issues with pre-built connectors and step-by-step solutions to debug integration problems.

Concepts

Events & Synchronization

Understanding work order events that trigger connector synchronization and how to configure event-based data flows.

Description

FN_WO_CREATED?event

Work order first created (may skip draft and go directly to published/routed)

FN_WO_DRAFT?event

Work order set to draft status after creation

FN_WO_PUBLISHED?event

Work order published and made available to providers

FN_WO_APPROVED?event

Work order approved and ready for execution

FN_WO_DELETED?event

Work order soft-deleted (set to delete status)

Provider Assignment

Prop

Type

Description

FN_WO_ROUTED?event

Work order routed to a provider (fires per provider - routing to 10 providers = 10 events)

FN_WO_STATUS_ROUTED?event

Work order status changed to routed (fires once regardless of provider count)

FN_WO_ASSIGNED?event

Work order assigned to provider (via routing acceptance or direct assignment)

FN_WO_CONFIRMED?event

Assigned provider confirmed acceptance

FN_WO_DECLINED?event

Provider declined work order (fires per decline)

FN_WO_UNDECLINED?event

Provider removed decline status

Work Execution

Prop

Type

Description

FN_WO_ON_MY_WAY?event

Provider marked status as 'on my way' to site

FN_WO_PROVIDER_CHECKED_IN?event

Provider checked in (fires per check-in if multiple)

FN_WO_PROVIDER_CHECKED_OUT?event

Provider checked out (fires per check-out if multiple)

FN_WO_TASK_COMPLETED?event

Individual task within work order completed

FN_WO_DONE?event

Provider marked entire work order as completed

Schedule & Timeline

Prop

Type

Description

FN_WO_SCHEDULE_UPDATED?event

Schedule modified (date, time, or duration changed)

FN_WO_DELAYED?event

Work order delayed (typically on-hold status)

FN_WO_POSTPONED?event

Work order postponed indefinitely

FN_WO_AT_RISK?event

System detected work order at risk of not completing on time

Updates & Changes

Prop

Type

Description

FN_WO_UPDATED?event

Basic work order information changed (title, description, core fields)

FN_WO_CUSTOM_FIELD_VALUE_UPDATED?event

Any custom field value updated

FN_WO_SHIPMENT_UPDATED?event

Shipment information modified

FN_WO_INTEGRATION_STATUS_UPDATED?event

Integration-specific status field changed

FN_WO_ALERTS_SENT?event

Alert notifications sent for work order

Messages & Communication

Prop

Type

Description

FN_WO_MESSAGE_ADDED?event

New message added to work order thread

FN_WO_TASK_MESSAGE_ADDED?event

Message added to specific task within work order

FN_WO_CLOSE_OUT_ADDED?event

Close-out information or notes added

Financial Events

Prop

Type

Description

FN_WO_PAYMENT_APPROVED?event

Payment for work order approved

FN_WO_EXPENSE_ADDED?event

Expense item added to work order

FN_WO_COUNTER_OFFER?event

Provider submitted counter-offer for payment terms

Additional Events

Prop

Type

Description

FN_WO_ATTACHMENT_ADDED?event

File or attachment added to work order

FN_WO_CANCELLED?event

Work order cancelled

FN_WO_PENDING_QUALIFICATIONS?event

Work order has pending qualification requirements

FN_WO_PROBLEM_REPORTED?event

Issue or problem reported on work order

✅ FN_WO_ASSIGNED - Sync when provider assigned
✅ FN_WO_DONE - Sync when work completed
✅ FN_WO_APPROVED - Sync when work approved

Configure Action

For each event, specify the action:

Update Record - Update existing external record
Create Record - Create new external record (typically for messages/notes)
Custom Script - Run platform-specific logic

Save Configuration

Test event triggers with sample work orders

Common Event Configurations

Minimal Sync (Status Only)

FN_WO_ASSIGNED - Provider assigned
FN_WO_DONE - Work completed
FN_WO_APPROVED - Work approved

Standard Sync (Status + Communication)

All minimal sync events
FN_WO_MESSAGE_ADDED - Sync messages
FN_WO_SCHEDULE_UPDATED - Sync schedule changes
FN_WO_CUSTOM_FIELD_VALUE_UPDATED - Sync custom fields

Comprehensive Sync (Full Lifecycle)

All standard sync events
FN_WO_ON_MY_WAY - Provider en route
FN_WO_PROVIDER_CHECKED_IN - Check-in tracking
FN_WO_PROVIDER_CHECKED_OUT - Check-out tracking
FN_WO_PAYMENT_APPROVED - Financial tracking
FN_WO_ATTACHMENT_ADDED - Document sync

Synchronization Patterns

Inbound: External System → Field Nation

External systems trigger synchronization via webhooks:

Loading diagram...

Triggers:

Record created in external system
Record status changed
Record field updated (specific fields)
Manual "Sync to Field Nation" button

Outbound: Field Nation → External System

Field Nation events trigger synchronization:

Loading diagram...

Triggers:

Configured Field Nation events
Status changes
Custom field updates
Message additions

Event Payloads

Events include complete work order context:

{
  "event_type": "FN_WO_ASSIGNED",
  "event_timestamp": "2025-01-15T14:30:00Z",
  "workorder": {
    "id": 12345678,
    "title": "On-site Network Installation",
    "status": {
      "id": 2,
      "name": "assigned"
    },
    "assignee": {
      "user": {
        "id": 987654,
        "first_name": "John",
        "last_name": "Technician",
        "email": "john@example.com",
        "phone": "+1-555-0100"
      }
    },
    "schedule": {
      "service_window": {
        "start": {
          "utc": "2025-01-20 09:00:00"
        },
        "end": {
          "utc": "2025-01-20 12:00:00"
        }
      }
    },
    "pay": {
      "type": "fixed",
      "amount": 250.00
    },
    "custom_fields": [ /* ... */ ]
  },
  "correlation_id": "ext-record-456"
}

Map statuses bidirectionally (FN → External and External → FN)
Use correlation IDs to track related records
Handle sync conflicts (last-write-wins or manual resolution)

Idempotency

Ensure same event processed multiple times produces same result
Check correlation ID before creating new records
Use upsert logic (create if not exists, update if exists)

Error Handling

Configure retries for temporary failures
Set up dead letter queue monitoring
Alert on persistent sync failures

Monitoring Event Sync

Integration Logs

Track event processing in Integration Broker logs:

Event received timestamp
Field mappings applied
API call made to external system
Success/failure status
Error details (if failed)

Health Metrics

Monitor key indicators:

Event Processing Rate: Events/minute
Success Rate: % successful syncs
Average Latency: Time from event to external update
Error Rate: % failed syncs
Queue Depth: Pending events in queue

Troubleshooting Events

Complete troubleshooting guide →

Last updated on

Custom Actions with JSONNET

Write advanced data transformation logic using JSONNET for complex field mapping scenarios.

Troubleshooting

Common issues with pre-built connectors and step-by-step solutions to debug integration problems.

Events & Synchronization

Start with Core Events

Avoid Redundant Events

Consider Event Volume

Events Not Triggering

Events Triggering Multiple Times

External System Not Updating

On this page

Events & Synchronization

Start with Core Events

Avoid Redundant Events

Consider Event Volume

Events Not Triggering

Events Triggering Multiple Times

External System Not Updating

On this page