Vendor integrations — connect, import and match animals

Admin portal → Vendor integrations connects a vendor data source to a particular farm. Select the correct organisation first if you administer several, then use the searchable Farm selector. The first farm is selected automatically on the initial unfiltered load; always confirm its name before changing a connection. Search is sent to the server as you type, so a farm beyond the first page can still be found. Tenant or Platform Admin access is needed to manage these connections, and adding, configuring or resuming one requires the Vendor Integrations subscription feature.

This screen currently configures a vendor CSV import source. Manual CSV is the only implemented ingestion mode. It does not ask for an OAuth login, API key or password, or offer a scheduled polling control. Webhook or polling will appear only after Farmlync has a code-backed adapter for that vendor. Farmlync consumes confirmed vendor data; it does not register or manage the physical collar, robot or parlour.

Add or configure a connection

Select Add integration. If the feature is unavailable, Review access leads to Billing & Plan. If no vendor definitions exist, a Platform Admin must add or seed them before this form can be completed. The slide-over loads its options, then shows:

Control	What to enter or choose
Display name	A required name that distinguishes this farm’s connection in the list, such as the vendor and site.
Integration type	A required category such as heat detection, milk parlour or weigh/EID. Only types with an enabled vendor definition appear. Changing it can clear the previously selected vendor and modes.
Vendor	A required enabled vendor within the chosen type. Choose Generic CSV under Other only when the file uses Farmlync’s canonical column names.
Expected CSV columns	Read-only guidance from the selected vendor definition: column names, and where configured, date formats and reading labels. Use it to prepare the upload.
External vendor field	Read-only name of the source animal identifier column.
Match to Farmlync identifier	Required identifier scheme for matching vendor animals to Farmlync animals. The offered schemes are limited to those supported by the selected provider when it declares a limit. Choose the actual identifier in the file. ExternalOpaque uses the vendor’s own identifier and may need manual matches.
Auto-learn mapping	On by default. Remembers a confirmed vendor-ID-to-animal match for later readings.
Modes	Keep CSV / manual upload checked for the current implementation. The form shows only code-backed modes available to that vendor. Clearing every checkbox currently restores the CSV default when saved rather than producing a connection with no mode; this is recorded as a product gap.
External account ID	Optional vendor account/site reference on Add. It is not a credential field and does not appear in the Configure form.

Select Add integration to create the connection. Configure reopens the slide-over with the current values; Save changes updates its name, identifier scheme, auto-learning setting, vendor profile and modes. The form does not edit its External account ID. Wait for the success toast; validation or API errors appear in the panel.

Read and operate the connection list

Each desktop row shows Integration name and whether credentials are set, Type, Animal-ID scheme, Modes, Status, Last sync and Actions. Mobile uses cards for the same connection. Import data is shown when Manual CSV is enabled. Mapping issues opens unresolved vendor records. Configure changes the supported settings. Pause changes an Active or Error connection to Paused; Resume is available for a Paused one when the feature is entitled. Delete soft-deletes the connection and asks for confirmation because the action has no restore control.

The current import handler does not enforce connection status, and the page continues to offer manual import on a Paused connection. Treat Pause as incomplete protection until the recorded product gap is fixed. If the subscription feature is no longer available, the UI prevents add, configure and resume, but still exposes manual import and the import endpoint is not entitlement-gated. That downgrade behavior is also recorded for correction rather than presented as intended access.

Upload a vendor CSV

Select a connection’s Import data action. On Import vendor data, verify Integration; the first available connection may be preselected. Read Expected CSV columns, any vendor-specific reading labels/date formats and Download sample CSV. For the built-in canonical layout, measuredAt must be ISO 8601 with a timezone; a row can supply vendorDeviceId, vendorAnimalId or both. The other canonical fields are readingType, numericValue, sourceUnit and vendorEventId. A curated vendor profile may use different headings, which the import maps to these fields.

Select Choose CSV file and then Import vendor data. The file is read in full by the browser and submitted as text under the selected connection. There is no pre-submit row preview, file-size check or row-count check on this page. The server’s synchronous limit is 5,000 parsed rows, and the normal JSON request limit can reject a large file before parsing; split large exports before upload. The import fails as a whole when the CSV header or any row cannot be parsed. If there is no configured connection, the upload is blocked and the page points an administrator to Add an integration.

After a structurally valid file is submitted, read the Import summary: total rows, Accepted, Applied to workflows, Retained only, Duplicates, Mapping issues, Quarantined, Failed and Missing source identifier. Accepted is the number that completed processing; Applied to workflows is the subset that created an operational effect. Retained only means the record was accepted and stored but its reading type has no owning workflow effect. Duplicates include an event already imported for this data source and a repeated event ID inside the same file. Expand the listed errors and resolve source problems before another import. An Accepted count alone does not mean every record affected an animal workflow.

For the canonical layout, a blank vendorEventId is allowed: Farmlync builds a stable ID from the source or animal identifier, reading type and measurement timestamp so a re-upload can deduplicate it. A row with neither vendorDeviceId nor vendorAnimalId is invalid. Supported canonical reading types are HeatAlert, ActivityIndex, MilkYield, Weight and EidScan; a vendor profile may translate its own labels to these values. Weight readings also require a recognized unit and are not applied to an animal that did not belong to the farm at the measurement time.

Resolve animal mapping issues

Open Mapping issues from the connection row or the import summary. The page lists unmatched records in server-backed pages of 20, with vendor source, reading type, measured time, vendor animal ID and failure reason. It refreshes every 30 seconds. Select Resolve only after comparing the external ID with the intended Farmlync animal. The slide-over requires an animal from this farm and has Create mapping for future readings on by default.

Leave the mapping option checked when that vendor identifier consistently represents the same animal. The mapping begins at this reading’s measurement time. If the same source identifier currently points to another animal, Farmlync ends the old mapping at that time and opens a new validity window, preserving historical attribution. Clear it for a one-off correction that should pin only this record. Select Resolve to reset the record for processing and run it through the normal pipeline again. A weight reading is rejected if the chosen animal did not belong to the farm or was already inactive at the measurement time. Check the returned status and the relevant animal/workflow; an empty list means there are no currently unmatched records for that connection.