Flocks and sharing

How a flock reaches records: one mechanism, sharing — what it can do, what it can never do, and where to look when it is not working.

On Emu Watch, the Coastal Volunteers can see Priya's season of sightings. This page is about how that sentence becomes true.

Flocks are crews in the API: the dashboard says flock, the endpoints and the SDK say crew.

The short version:

A flock reaches a record through a share. Whoever owns the record hands it to the flock, at a level, one record at a time — and can take it back.

There used to be a second way, and if you have used EmuView before you may be looking for it. Flock scoping — a crew_id on every row, dividing a whole collection between flocks structurally — has been removed. Sharing does what it did and more, and having two mechanisms meant every read path, write path and audit surface had to agree about both. See flock record access for what to do instead, and what an operator has to run before upgrading.

#The handed-over season

Sharing is Priya handing her season to the flock. The sightings are hers, they live in the ordinary sightings collection alongside everyone else's, and she decided — for these records, this once — that the Coastal Volunteers get them, and whether the flock may write on them. Nobody else's sightings are affected, and Priya can take them back.

That is the whole model. What varies is the level she grants and how long it lasts.

#What decides what a flock member can do

Three things, in this order, and each one only narrows:

Layer	Question it answers	Set by
Their role	May they do this at all, anywhere?	An administrator
The share	Does this record reach them, and at what level?	Whoever owns the record
Their tier	How far may they go on what the flock is given?	A manager of the flock

A manage share to the Coastal Volunteers still gives Ben — a viewer in that flock — nothing but read. The tier caps the share; it never grants anything on its own. A share naming a person has no flock standing in it, so only the level and their role apply.

#When to reach for a flock rather than a person

If this is true…	Share with…
The same records should reach a group that changes over time	A flock
People join and leave, and access should follow	A flock
One named person needs one record	A person
The same record needs to reach two different groups	Two shares
You want the access to expire on a date	Either, `expiresAt`

Sharing with a flock is the one that scales: add somebody to the Coastal Volunteers and every record shared with that flock appears for them on their next request. Remove them and it is gone.

Sharing is on by default, and a collection can turn it off or limit it to curators — see Is sharing available here?. Where it is on, whoever owns a record or a file can hand it on, and there are three ways to say who:

By name. Priya shares one sighting with Ben — pick people, choose what each may do. Best for a handful of specific people. Nothing else has to exist first, and Ben does not need to be in any flock.

With a flock. Priya shares a season with the Coastal Volunteers — everyone in it reaches the sightings, and the list stays correct as people join and leave. Best when the audience is a group that changes.

Three levels, each including the ones before it:

Level	Can
View	See it
Edit	See and change it
Manage	See, change, and share it onward

Editing does not include sharing. That is deliberate. If it did, anyone you let edit something could hand it to people you have never heard of, and you would never be told. Only Manage carries that, and the owner always has it.

Full detail: sharing an item.

#The whole thing on one site

Emu Watch, end to end. Every line below is a different mechanism, and they stack without any of them being a row filter on the collection.

Sightings — every sighting belongs to whoever logged it, and most are private.

Priya logs a sighting. Only Priya can see it. Priya shares a season with the Coastal Volunteers at Edit. Ana, an editor in the flock, corrects the species names; Ben, a viewer, just looks. Priya still owns every sighting. Priya also shares one sighting by name with Ben at View, because she wants a second opinion on the identification and he is in no flock that reaches it. The public map is neither of these — it is a collection rule: everyone may view sightings where status is verified.

And the case that used to need flock scoping:

The same site gives each flock its own survey notes — patrol plans, meeting minutes, equipment lists. That collection is set to Their own, so a record is private to whoever wrote it, and each note is shared with the flock it was written for, at Edit or Manage.

The Rangers never see the Coastal Volunteers' plans, because no share reaches them. The difference from the old flock-scoped collection is that the reach is now visible: System → Access lists every share a flock holds, where the old column showed only a value sitting in a row.

This is the rule that surprises people, and it is worth stating on its own.

A share widens WHICH items somebody reaches. It never widens WHAT they may do.

If Ben's role cannot edit sightings, then sharing a sighting with Ben at Edit gives him nothing extra — he will be able to view it and no more. The share is not ignored; it is capped.

This is what keeps things safe when anybody can create a flock and invite anybody. Handing something out can never promote a person, so the worst an over-generous share can do is show somebody a record. It can never turn a reader into a writer.

The same goes for a person's place in a flock: being an admin of the Coastal Volunteers makes Priya an admin of that flock — its members, its shares. It grants nothing anywhere else.

And one thing outranks both mechanisms: a never-rule. A sighting at a sensitive nesting site is invisible through the survey notes, through every share, and to the owner — no matter which of the two you used.

#Making something does not give you a claim on it forever

The other rule that surprises people, and the one worth knowing before you change anybody's role.

What you can reach is decided by the role you have now — not by what you made in the past.

Priya files sightings into the Coastal Volunteers' survey notes for a year. Then she leaves the flock. From that moment those records are outside what her role reaches, and they are gone from her view — including the ones she wrote herself. She is still recorded as their author; that never changes and it is not what decides access.

This is deliberate, and the alternative is worse. If making something gave you a permanent claim on it, then nobody could ever truly have their access removed: somebody who left the flock last year, or the site altogether, would keep a private door into every record they had ever created, and no amount of taking roles away would close it. Offboarding somebody has to actually offboard them.

It applies everywhere, not just to lists. The collection, the search, the Share tab, the API — they all answer the same way, because they all ask the same question. And it applies to whoever holds a record now: handing a record to somebody the rules do not reach does not create a claim for them either.

#What this looks like in practice

Priya, after leaving the flock	What happens
Opens the note she wrote	Not found — the same answer as for a record that was deleted
Opens the Share tab on it	Not found
Tries to share it with Ben	Not found
Tries to revoke the share she made to the flock	Refused — see below

"Not found" is the answer to all three, and that is on purpose. A record outside what your role reaches has to look exactly like a record that is not there, or the refusal itself becomes a way to go fishing: try an address, and a "you may not share this" would confirm something is at it while "not found" would say nothing is. So the answer never distinguishes the two — not in the record, not in the Share tab, and not when you try to share.

Somebody who can see the record gets a reason instead, because there is nothing left to hide from them: a person the record is shared with for viewing, or an administrator, is told only the owner, or someone with Manage, can share it — which is the sentence that says what to ask for.

The revoke row is the one to plan for. Demoting somebody does not withdraw the things they shared, and afterwards they cannot withdraw them either. The Coastal Volunteers keep the season Priya gave them; Priya can no longer take it back.

#Records that end up needing an administrator

A record ends up reachable only through an administrator whenever the person who holds it falls outside the rules, and nobody else has been given Manage on it. The usual ways that happens:

somebody leaves a flock while records filed to that flock are theirs;
somebody's role changes to one with a narrower reach — from "all records" to "their own", or to a flock they are not in;
somebody else moves the record into a flock its owner is not in;
a record is handed over to somebody whose role does not reach it — they own it and still cannot see it, because owning it was never what decided that;
a never-rule matches it, which is the one case where not even an administrator gets it back until the rule is changed.

An administrator whose role is not restricted to particular rows still has the record itself: they can open it, edit it, and hand it to somebody who can look after it. Sharing is the part that goes with ownership, so to manage a stranded record's audience they take ownership first — Hand over on the record, then the Share tab works as usual.

Hand records over first, then change the role. If somebody is leaving a flock, a team or the site, give their records to whoever is taking them on before you narrow what they can reach. It costs a minute at the time, and an administrator's afternoon afterwards.

#Where to look when it is not working

Symptom	Look at
"I shared it and they still can't edit"	Their role. A share cannot add an action.
"They can edit in one flock but not another"	Their tier in that flock. A viewer there caps at view.
"Records vanished after an upgrade"	Flock scoping was removed. Records now reach a flock through a share — see flock record access.
"They can see more than I expected"	System → Access, which reports share counts too.
"I can't share it at all"	Check the collection's sharing setting first — it may be off, or limited to curators. Otherwise you must own it, or hold Manage on it.
"Nobody can see it, even the owner"	A never-rule matches it.
"I made this record and now I can't see it"	Your role's reach changed, or a share was revoked. Making it does not keep it.

The access inspector under System → Access will show you, for any person or flock, both their roles and how many items are shared with them — which between them account for everything they can reach.

#Next

Sharing an item — levels, expiry, revoking, and who may share
Roles — what a role actually is, in detail
Recipes — Emu Watch's setups, ready to copy
Flock record access — what replaced flock scoping, and what an operator must run before upgrading