Sync Configuration

Control how and when data flows between Microsoft Dynamics 365 Business Central and the EUDR platform.

Sync Methods

Manual Sync (Pull)

Trigger a sync on-demand from the UI or via API:

POST /api/integrations/:id/dynamics/sync
Content-Type: application/json

{
  "modifiedSince": "2024-01-15T00:00:00Z"
}

Omit modifiedSince for a full sync of all records.

API-Triggered Sync

Integrate sync into your CI/CD or scheduled tasks:

curl -X POST https://backend.joinnentropy.com/api/integrations/{id}/dynamics/sync \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{"modifiedSince": "2024-06-01T00:00:00Z"}'

Response:

{
  "success": true,
  "data": {
    "suppliers": { "created": 5, "updated": 12, "errors": 0 },
    "products": { "created": 3, "updated": 8, "errors": 1 }
  }
}

Sync Scope

Each sync operation processes two entity types:

BC Entity	Platform Entity	Direction
Vendors	Suppliers	BC → Platform
Items	Products	BC → Platform

Full Sync

Fetches all records from Business Central. Use this for:

Initial data import
Periodic full reconciliation
After fixing mapping issues

Delta Sync

Use the modifiedSince parameter to only fetch records changed after a specific timestamp. This is significantly faster for large datasets.

The platform stores lastSyncedAt on each integration to help track the last successful sync time.

Conflict Resolution

When a record exists in both systems, the sync engine applies these rules:

Scenario	Behavior
New record in BC	Created in platform
Updated record in BC	Updated in platform (BC wins)
Deleted record in BC	Not deleted in platform
New record in platform	Not synced to BC
Updated record in platform	Not synced to BC

Record Matching

Records are matched using a composite key:

externalId — The Business Central record ID
externalSystem — Always dynamics_bc
userId — The platform user who owns the integration

This means the same BC record can be synced by different platform users without conflicts.

Sync Status

Each synced record has a syncStatus field:

Status	Description
`pending`	Record queued for sync
`synced`	Successfully synced
`error`	Sync failed (check sync logs)
`conflict`	Manual resolution needed

Sync Logs

Every sync operation creates detailed logs accessible via:

UI: Integrations → Sync History tab
API: GET /api/integrations/:id/sync-logs

Each log entry contains:

{
  "id": "log-123",
  "integrationId": "int-456",
  "entityType": "SUPPLIER",
  "action": "UPSERT",
  "status": "SUCCESS",
  "recordsAffected": 17,
  "metadata": {
    "created": 5,
    "updated": 12,
    "errors": []
  },
  "createdAt": "2024-06-15T10:30:00Z"
}

Error Handling

Partial Failures

If some records fail during sync, the operation continues with remaining records. Failed records are logged individually in the sync metadata:

{
  "errors": [
    {
      "externalId": "vendor-789",
      "error": "Missing required field: name",
      "data": { "displayName": null }
    }
  ]
}

Token Expiration

OAuth tokens expire after ~1 hour. The platform automatically refreshes tokens using the stored refresh token. If the refresh token also expires (typically after 90 days), you’ll need to re-authorize the connection.

Rate Limiting

Business Central API has rate limits. The sync engine handles 429 Too Many Requests responses by pausing and retrying. For large datasets, consider syncing during off-peak hours.

Testing

Before running a production sync, use the test connection feature:

POST /api/integrations/:id/dynamics/test

This verifies:

OAuth credentials are valid
Business Central API is reachable
The integration can list companies
Read permissions are working

Response:

{
  "success": true,
  "data": {
    "connected": true,
    "company": "CRONUS International Ltd.",
    "vendorCount": 45,
    "itemCount": 230
  }
}

Best Practices

Start with sandbox: Test your integration against a BC sandbox environment first
Use delta sync: For regular syncs, always use modifiedSince to minimize API calls
Monitor sync logs: Review the Sync History tab regularly for errors
Set up webhooks: Configure webhooks to get notified of sync completions and failures
Map custom fields: If your BC instance has EUDR-relevant custom fields, configure them in Sync Config