Customizing Data Sync

By default, when a credential is added to a Leaf user, all available data is fetched. However, for certain use cases, it is essential to be able to customize exactly which data will be synchronized to Leaf.

This document outlines how to customize the data that Leaf retrieves at various hierarchical levels.

Filtering by organization

For providers with data organized by organization or company, Leaf allows the selection of specific organizations and limits data sync to just those, reducing unnecessary data.

1 - Configuration

Enabling organization custom data synchronization is possible using the organizationsDataSync configuration.

It can be set at API Owner or Leaf user level and it is essential to be defined before the credentials attachment.

2 - Get all organizations

After connecting a new John Deere credential, all the organizations available on the provider side can be retrieved using the organizations endpoint.

Response

With the organizationsDataSync configuration set as "SELECTED_ONLY" all organizations, initially, will have the status "PREVIEW”. It means no other additional data like Field Boundaries or Operations will be fetched from that organization until it is changed to "SELECTED".

The organization selection can be done using the PATCH organization endpoint.

Response:

After this request, all data related to the selected organization will be synchronized. The sync process starts immediately after the request, and the fields should be fetched almost immediately.

Filtering by fields

Leaf API enables the selection of fields for scenarios where growers don't want to integrate all their fields and related data. It is possible to use the customDataSync configuration.

When it is enabled, all fields are fetched from the provider as "PREVIEW”, which means, it has the attributes but no boundary associated with it. For Deere and Climate, the machine operations from those fields are not fetched as well.

This way, for field selection, the resources can be listed following these instructions:

1 - Listing resources

Users can select which resources to synchronize including fields, farms, and growers:

Listing fields

Listing farms

Listing growers

You can combine the resources you select, for example using a UI:

2 - Enabling Fields

After selecting resources, you can enable fields individually or by grower ID:

Enabling a single field

This endpoint allows a single field to be marked to be synchronized in the next synchronization window.

Enabling fields by grower list

This endpoint allows multiple fields to be synchronized based on a list of the grower's IDs (id from /growers endpoint).

Payload: list of the Leaf grower's ID

Important Notes

New fields are fetched in PREVIEW mode. To sync fields from organizations where data sync is needed, you must enable them. You can either enable a single field or enable fields by grower (see above for details on these).

Preview mode is applied to all providers, so enabling the sync for all desired fields is necessary.

For cases where the endpoint to enable fields per grower is used, avoid making multiple calls sending one grower at a time, instead send them as a list in the payload. It will avoid unnecessary synchronizations.

This tutorial serves as an alternative solution to an organization management feature planned for future releases.

organizationDataSync x customDataSync