Connect and import vendor data

What this workflow does

Use this workflow when confirmed data exported by a vendor must enter Farmlync. Examples include milk yield, weight, activity, heat alerts and EID scans. The connection tells Farmlync which file layout to expect and how the vendor identifies animals.

Farmlync does not register, configure or control a physical collar, robot, parlour or reader. The current customer workflow imports vendor CSV files. It does not collect an OAuth login, API key or password, and it does not offer scheduled polling. A Platform Admin must first enable an appropriate vendor definition before a farm can select it.

Before you begin

You need Tenant Admin or Platform Admin access and the organisation must have the Vendor Integrations subscription feature. If Add integration is replaced by Review access, open Billing & Plan and check the organisation’s entitlement.

Before creating a connection, confirm:

• the organisation and farm that own the source data;
• the vendor product and integration type;
• whether the file is a vendor-specific export or Farmlync’s canonical CSV layout;
• the animal identifier carried in the file, such as tag number, National ID, RFID or a vendor-only ID;
• the file headings, reading labels, units and date format; and
• that timestamps identify the actual measurement time and include a timezone when the profile requires one.

Do not import a trial file into a farm merely because its format looks correct. The chosen farm determines which animals can be matched and where accepted readings are applied.

1. Select the organisation and farm

1. Open Admin → Vendor integrations.
2. If you administer several organisations, select the organisation that owns the connection.
3. Use the searchable Farm selector to find the farm. Search is sent to the server, so farms beyond the first page can still be found.
4. Read the selected farm name before continuing. The first farm can be selected automatically on the initial unfiltered load.

Connections belong to one farm. Create a separate connection when another farm receives data from the same vendor.

2. Add the connection

Select Add integration and complete the slide-over.

Control	Required	What to enter or choose
Display name	Yes	A recognizable name for this farm and source, such as Lely parlour — home unit. It distinguishes the connection in lists and import screens.
Integration type	Yes	The source category, such as heat detection, milk parlour or weigh/EID. Only types backed by an enabled platform definition appear. Changing the type can clear the selected vendor and modes.
Vendor	Yes	The enabled vendor profile within the selected type. Use Generic CSV under Other only when the export already uses Farmlync’s canonical columns.
Expected CSV columns	Read-only	The column names expected by the selected profile and, when configured, its date formats and reading labels. Use this information to prepare the source file.
External vendor field	Read-only	The vendor column used as the source animal identifier.
Match to Farmlync identifier	Yes	The Farmlync identifier represented by the external field. The available schemes may be limited by the vendor profile. Choose the identifier actually present in the export.
Auto-learn mapping	No; on by default	Keeps a confirmed vendor-ID-to-animal match for later readings. Leave it on when the external ID consistently identifies the same animal.
Modes	Yes in practice	Keep CSV / manual upload selected. Manual CSV is the only currently implemented ingestion mode. Clearing all modes currently restores the CSV default when saved.
External account ID	No	The vendor’s site or account reference. It is not a credential. It is available when adding the connection and is not editable in Configure.

Choose ExternalOpaque as the matching scheme only when the vendor supplies its own identifier rather than a recognized Farmlync animal identifier. Those readings may need a manual mapping before they can be applied.

Select Add integration and wait for the success message. In the connection list, verify its Integration name, Type, Animal-ID scheme, Modes, Status and Last sync.

3. Prepare the CSV file

From the connection row, select Import data. Verify the Integration at the top of the page; the first available connection can be preselected. Compare the vendor export with Expected CSV columns, and use Download sample CSV when available.

A curated vendor profile can use its own headings and labels. Upload that vendor’s original supported layout; Farmlync maps it to its canonical readings. The Generic CSV layout uses:

Column	What it represents
measuredAt	Actual measurement timestamp. Use ISO 8601 with a timezone in the canonical layout.
vendorDeviceId	Source device identifier, when supplied.
vendorAnimalId	Animal identifier from the vendor. A row must contain this field, vendorDeviceId, or both.
readingType	Canonical type: HeatAlert, ActivityIndex, MilkYield, Weight or EidScan. A curated profile can translate vendor labels into these values.
numericValue	Numeric reading value where the reading type requires it.
sourceUnit	Unit supplied by the source. Weight readings require a recognized unit.
vendorEventId	Stable event identifier when the vendor supplies one. It can be blank; Farmlync then derives a stable identifier from the source, animal, reading type and measurement time.

Inspect the entire file before upload. The page has no row preview, file-size check or row-count check. The server processes at most 5,000 parsed rows synchronously, and a large request can be rejected before parsing. Split a larger export into smaller files. A malformed header or unparseable row causes the whole import request to fail.

4. Import the data

1. Select Choose CSV file and choose the reviewed export.
2. Recheck the connection and file name.
3. Select Import vendor data once and leave the page open while it runs.
4. Read every value in the Import summary.

Result	Meaning
Total rows	Parsed source rows considered by the import.
Accepted	Rows that completed import processing. This does not by itself prove that an operational record changed.
Applied to workflows	Accepted readings that produced a supported Farmlync operational effect.
Retained only	Farmlync stored the vendor reading, but its type had no owning workflow effect.
Duplicates	Readings already received for this source, including repeated event IDs inside the same file. They are not applied twice.
Mapping issues	Readings whose animal could not be matched confidently.
Quarantined	Readings retained for review instead of being applied.
Failed	Rows that could not be processed. Expand the errors and correct the source before retrying.
Missing source identifier	Rows with neither of the identifiers needed by the configured matching rule.

An Accepted count can be greater than Applied to workflows. Treat Applied to workflows and verification in the owning feature as the evidence that the data affected farm records.

5. Resolve animal mapping issues

Open Mapping issues from the connection row or import summary. The page displays server-backed pages of 20 and refreshes every 30 seconds. Each row identifies the vendor source, reading type, measurement time, vendor animal ID and reason it could not be matched.

For each issue:

1. Compare the vendor animal ID with the animal’s physical tag and identifiers in Farmlync.
2. Select Resolve only when the match is known.
3. Search for and select the correct animal from this farm.
4. Leave Create mapping for future readings on when this external ID will continue to identify the same animal.
5. Clear that option for a one-off correction that must not establish an ongoing mapping.
6. Select Resolve and read the returned status.

A saved mapping starts at the reading’s measurement time. If the same vendor identifier currently maps to another animal, Farmlync closes the previous validity window and begins the new one, preserving historical attribution. A one-off resolution pins only the selected record.

Farmlync rejects a weight reading when the chosen animal did not belong to this farm, or was already inactive, at the measurement time. Investigate the date and animal history rather than forcing the reading onto its current holder.

6. Verify the operational result

After the import and any mapping resolution:

1. Open the feature that owns the reading—for example an animal’s milk, weight, breeding or health history.
2. Inspect a sample from the beginning, middle and end of the imported period.
3. Confirm the animal, farm, measurement time, value and unit.
4. Compare Applied to workflows, Retained only, Duplicates, Failed, Quarantined and unresolved mapping counts with the expected file contents.
5. Correct the source file before importing again. A stable vendor event ID, or Farmlync’s derived identifier, prevents an accepted reading from being applied twice.

An empty mapping-issue list means there are no currently unresolved readings for that connection. It does not prove that every accepted reading created an operational effect.

7. Maintain or remove the connection

Use the connection-row actions carefully:

• Configure changes the display name, identifier scheme, auto-learning choice, vendor profile and supported modes. It does not edit the External account ID.
• Pause changes an Active or Error connection to Paused.
• Resume reactivates a paused connection when the organisation remains entitled.
• Delete soft-deletes the connection after confirmation. The page has no restore action.

The current manual import path remains available on a paused connection and after a Vendor Integrations entitlement downgrade. Until those recorded product gaps are corrected, do not rely on Pause or an entitlement change as the only operational control. Remove access to the source file and avoid importing into that connection.

Completion checklist

• The correct organisation and farm are selected.
• The connection uses the intended vendor profile and animal identifier scheme.
• The CSV matches the displayed profile and contains no more than 5,000 rows.
• Import errors and mapping issues have been reviewed individually.
• Persistent mappings were created only for known animal identities.
• A sample of applied readings was verified in its owning Farmlync feature.
• Duplicate and retained-only counts are understood before the import is considered complete.

For page-level reference, see Vendor integrations — connect, import and match animals and Integrations and imports.