Configure organisation and farm defaults

What this workflow sets up

Use this workflow after organisation onboarding and before importing many animals or recording milk, treatments, breeding work or stock. It establishes the settings that Farmlync uses to interpret farm-local dates, display measurements, validate animal identifiers, generate work, plan breeding and lifecycle events, and offer farms, pens and counterparties in later forms.

Complete the work in this order:

1. confirm the selected organisation and its plan;
2. set organisation-wide operating defaults;
3. create and verify each farm;
4. add only the farm-specific livestock overrides that are genuinely different;
5. create physical pens and organisation-wide parties needed by daily work; and
6. verify the result in the forms that operators will use.

Authority: a Tenant Admin manages organisation settings and creates farms. A Platform Admin can do the same after selecting the intended customer organisation. Farm Owners and Managers can maintain many settings inside farms they manage, but structural changes have narrower permissions. The detailed sections below identify those differences.

Always confirm the current organisation and farm

Platform Administrators and users who belong to several organisations or farms can change context from the header. Before saving, check both the selected organisation and the farm named on the page. Organisation settings affect every farm that inherits them; farm settings affect only the named farm.

1. Confirm the organisation and plan

Open Admin → Organisation. This is a read-only overview, not the organisation editor.

1. Confirm the organisation name in the header.
2. Review Subscription plan, Farms, Animal usage, Active users and Member since.
3. Use Billing & Plan for the authoritative plan, quota and subscription actions. A temporarily missing limit on the overview is not proof that capacity is unlimited.
4. If the business name is wrong, ask a Platform Admin to correct it from Platform → Tenants before creating similarly named farms.

The organisation owns the subscription, users and shared configuration. Farms beneath it own their herds and operational records. Read Organisation overview for the meaning of every card.

2. Set organisation-wide defaults

Open Admin → Settings. The page heading is Tenant Settings. Existing saved values must load before you edit. If the form looks unexpectedly empty or reset, refresh rather than saving an unverified form.

Localisation and milk measurement

Choose the organisation’s default display and measurement preferences:

Setting	Accepted choice or value	Operational effect
Weight Unit	kg or lb	Weight display and reports.
Volume Unit	Liters or gallons	General volume display; separate from the Milk Unit.
Temperature Unit	Celsius or Fahrenheit	Temperature display.
Date Format	DD/MM/YYYY, MM/DD/YYYY or YYYY-MM-DD	Date presentation.
Time Format	24-hour or 12-hour	Time presentation.
Currency	One offered currency code	Formats money; it does not convert historic values.
Language	One offered locale	Number and currency locale; it does not translate every Farmlync screen.
Timezone	Search and select an IANA timezone	Organisation preference/default. Every farm still needs its own actual timezone.
Milk Unit	Liters or kg	Interpretation and display of new milk quantities. Use Liters, not the currently rejected Litres option.
Milk Density	0.95–1.10 kg/L	Conversion between milk litres and kilograms.

Changing a milk unit while an external or offline client has unsent records can cause those values to be interpreted in the wrong unit. Resolve queued work before confirming the change. A currency change similarly changes formatting and does not recalculate earlier money values.

Livestock planning defaults

Set values agreed for the organisation’s normal operating model. Farms can override them later.

Setting	Accepted value
Gestation Period	200–400 days
Voluntary Waiting Period	0–120 days
Dry Period	0–120 days
Calf to Heifer Age	1–24 months
Default Lactation Length	100–500 days
Heat Interval	15–30 days
Days-Open Threshold	30–365 days
Services per Conception	1–10

These values inform forecasts, worklists and performance interpretation. They do not rewrite recorded calvings, services, treatments or other historical events. Avoid deliberately saving zero for Voluntary Waiting Period or Dry Period at present: the current form reloads a saved zero as its initial value and a later save can replace it.

Corrections, identification and modules

• Record Void Window accepts 0–168 hours. Zero removes the ordinary treatment/vaccination void option; it does not erase correction history.
• National ID label is required and accepts up to 60 characters. Use the name operators recognise for the official identifier.
• Require National ID becomes the inherited registration/import rule unless a farm overrides it.
• Milk Payout, Webhooks and AI Assistant module switches control visibility and API access. Turning a module off keeps its existing records. A switch cannot grant a feature missing from the subscription.

Read the After these changes are saved preview, choose Save Settings, and wait for Settings updated successfully. If another administrator saved first, choose Reload latest settings, compare the current record and reapply only the still-needed changes. Organisation settings — every control is the complete field reference.

3. Create the farm

Open Admin → Farms, select Create Farm, and complete the form once. Tenant and Platform Administrators can create a farm when the subscription permits it. Farm Owners and Managers cannot add another organisation farm from this page.

Field	What to enter
Farm Name	Required, up to 200 characters. Use the name shown in selectors and reports.
Farm Code	Required, up to 50 characters. Review the generated uppercase/hyphenated suggestion before saving; the normal edit form cannot change it later.
Timezone	Required IANA timezone for the farm’s physical location. This governs farm-local days, due work and interpretation of entered times.
Milking Sessions Per Day	1, 2, 3 or 4; the form starts at 2. This configures scheduling and does not create milk records.
Herd Type	Dairy, Beef or Mixed. It determines available livestock capabilities, so choose it before registering animals.
Default Breed	Optional organisation breed filtered for the chosen herd type. It prefills later registration and does not change existing animals.
Tag Label	Optional management-tag wording, such as Ear Tag or Freeze Brand. It is separate from National ID.
Address	Optional, up to 500 characters.
Latitude / Longitude	Optional coordinates; latitude −90 to 90 and longitude −180 to 180.
Government Registry	Optional enabled provider. Selecting it does not configure credentials or submit records.
Herd Registry Number	Optional provider/jurisdiction reference, up to 60 characters.
National ID label	Optional farm-specific label, up to 60 characters; blank inherits the organisation label.
National ID requirement	Inherit organisation default, Required on this farm, or Optional on this farm.

On success, the panel closes and the list refreshes. Find the new Farm Code, open the farm, and compare every displayed value with what you intended. If quota or validation rejects creation, correct the reported field and submit again rather than changing context or creating a second record.

4. Maintain farm identity and status safely

The farm detail is the setup hub. It links to users, shared-library adoption, livestock settings, groups, pens and registry configuration. Select Edit to change ordinary farm fields. Farm Code remains read-only.

Treat Herd Type as a structural decision:

• changing Dairy or Beef to Mixed adds capabilities;
• narrowing Mixed to one type, or swapping Dairy and Beef, removes capabilities;
• Farmlync refuses a narrowing change while incompatible active animals remain; and
• only a Farm Owner can make the structural change.

The edit flow saves ordinary fields first and sends a herd-type change separately. If the structural step is refused, the other edits may already be saved. Reopen the detail, inspect the actual values, and ask an Owner to complete the herd-type change rather than repeatedly submitting the whole form.

Use the status actions according to their effect:

Action	Effect
Deactivate	Removes the farm and its work from ordinary daily use while retaining records. Reactivate when it should return.
Delete	Owner-only, unavailable for the organisation’s last farm. Soft-deletes the farm and its animal groups.
Restore	Restores the farm and its pens, but does not restore the groups deleted with it. Recreate required groups and memberships.

Prefer Deactivate when the farm may return. Do not use farm deletion as a correction for an animal or clinical record. See Farms — list, create and edit for search, filters, detail actions and exact status behaviour.

5. Add farm-specific livestock overrides

From farm detail select Livestock Settings, or use Farm Portal → Manage → Livestock settings.

An empty numeric control means inherit the displayed organisation default. It does not mean zero. Save only deliberate differences for this farm:

• breeding timing: voluntary waiting period, gestation length, heat interval, days-open threshold, services per conception and target conception rate;
• lifecycle readiness: calf-to-heifer age, minimum breeding age and optional target breeding weight;
• Dairy/Mixed planning: dry period and lactation length; and
• seasonal planning: calving pattern and optional breeding-season start/end dates.

If a target breeding weight is set, Farmlync requires weight evidence when evaluating maiden-heifer readiness. If both breeding-season dates are set, the end must be after the start. The season controls reporting windows; they do not record a breeding event.

Save settings replaces the farm’s complete override record. Blank values clear an override. If farm settings fail to load, use Retry and do not save the empty-looking form. If inherited hints unexpectedly say No tenant default, refresh and confirm the organisation settings loaded first. Then reopen the page and inspect the affected worklist or projection. Farm livestock settings lists every range and consequence.

6. Create physical pens

From farm detail, select Add Pen for each physical housing location that operators need to use. A pen is a barn pen, paddock, calving shed or other physical place. It is different from an Animal group, which is a logical working collection.

Pen control	What to enter
Pen Name	Required, 1–100 characters and unique within the farm.
Capacity	Optional whole number of at least 1. It is planning information and does not block over-capacity assignment.
Notes	Optional location context, up to 500 characters. Do not place clinical records here.

Creating a pen does not place animals in it or prove that feed was delivered. Assign animals separately; one batch supports up to 100 distinct animals. Farmlync records the previous pen, destination, reason and user in movement history. Move animals out before deleting a pen: deletion currently soft-deletes the location without clearing saved animal pen references. Read Pens — manage physical animal locations before assignment, bulk movement or deletion.

7. Create shared parties and contacts

Open Farm Portal → Manage → Suppliers, customers and contacts. Although opened from a farm, Parties is an organisation-wide register shared by all farms. Search before adding a record because duplicate names and registration numbers are currently allowed.

Select New party, enter a Name of up to 200 characters and choose at least one role:

• Abattoir
• AI technician
• Breed society
• Buyer
• Disposal collector
• Haulier
• Market
• Milk recording organisation
• Supplier
• Vet

Add the contact person, phone, email, legal name, registration number, VAT number, two-character country code, address, city, postcode and operational notes where relevant. A role makes the party available to matching selectors; it does not create a Farmlync login, a buyer route, a purchase order or a payment.

Archiving is immediate and has no confirmation. It hides the party from normal active selectors without erasing historical references. Turn on Show archived to restore it. Use Parties and contacts for every field limit, filter and downstream use.

8. Verify the working setup

Perform these checks before loading live records:

1. Open Livestock → Animals → Register Animal. Confirm the farm name, tag label, National ID label/requirement, default breed and valid herd choices. Close without saving a dummy animal.
2. Confirm the displayed farm-local date and time are correct for the farm, including across a calendar-day boundary if your user is in another timezone.
3. Open the farm’s Animals list and confirm Pen and Group are understood as separate concepts.
4. Open an inventory delivery, buyer, treatment or service form that uses a party and confirm the expected active role appears. Close without saving test data.
5. If a Government Registry is selected, configure its connection, credential and dispatch mode and follow Review government registry work before relying on submissions.
6. Continue with Set up the farm’s shared libraries, Set up health stock, Set up feed and stock and Set up semen stock as applicable.

The setup is complete when operators enter the correct farm automatically, see the expected field labels and units, receive work based on the intended thresholds, can choose the right physical locations and counterparties, and can distinguish inherited defaults from deliberate farm overrides.