Organization

Apps that serve more than one site need to know about places. A referral has to land somewhere; a supervisor should see their whole district while a clinic worker sees only their clinic; a form needs to name the site a worker belongs to. App setup → Organization is where you describe that structure.

There are three things on that screen, and the order is the order you build them: the levels of your organization, the information its places carry, and the places themselves.

Nova authors this model, and publishing puts these places on your CommCare HQ project space. Previewing as a persona shows what that worker's device would hold: their assigned places ride their session identity, case delivery decides which cases their lists show, and place-based case-owner expressions run when a form submits.

One owner rule still cannot be exported: a particular place, which names that place by Nova's own id rather than by the one CommCare HQ gave it. A place beneath the current case owner exports on every mode, because it travels as level codes and the case's own owner, both of which mean the same thing on CommCare HQ.

Levels

A level is a rung — Region, District, Facility, Ward. You add parent levels before their children. Levels may branch: for example, a Region can define District and Warehouse children without forcing either beneath the other.

Each level answers two questions, and the screen keeps them apart on purpose, because they are genuinely separate and mixing them up is the most common way an app ends up behaving strangely.

Case delivery

People work here decides whether workers can be assigned to places at this level.

Places here own cases decides whether cases can belong to a place at this level.

Those two are independent, and all four combinations are useful:

• Both on: an ordinary place people work out of. An assigned worker receives the cases their place owns. Previewing as a persona applies that delivery scope, so the case lists you see are the ones that worker's device would hold.
• Owns cases, nobody works here: a queue. Cases live there and reach nobody by assignment, which keeps a large backlog off every assigned worker's case list.
• People work here, owns nothing: an oversight rung. Everything those workers receive comes from the setting below.
• Neither: pure structure, a rung that exists so places below it have something to sit in.

Workers also receive cases from places below widens the delivery scope you are authoring, and Preview applies it the same way. "Everything below" is the common answer. On a real project space, stopping at a particular level also needs a setting on the CommCare project itself, which Nova does not configure. Publishing puts the places themselves on the project space.

Address-book reach

Seeing a place and receiving its cases are different things, and this is the setting people most often expect to do both. It does not. Widening it lets your expressions name more places; it moves no cases at all.

The choices:

• Their own place, everything under it, and the chain above — the default, and right for most levels.
• Their own place, but only certain levels — narrows a large tree to the rungs that matter. The choices stay contiguous from the worker's own level; a skipped rung would make CommCare unable to traverse to the deeper one.
• Everything under a level further up — lets a worker address places beside their own, such as the other clinics in their district.
• The whole organization — every place, for apps small enough to afford it.

Nova uses this footprint to validate whether an authored place-owner expression is safe for every assigned persona. It never filters a case list; that is case delivery's job. Widening it increases the location data CommCare HQ sends every worker at that level on restore, so that payload cost is the trade you are designing for.

Place information

Places already carry a name and a code. Place information is anything else you need on them — a phone number, a catchment population, an opening date.

Each entry has a name people read and a key CommCare stores it under. Nova checks that key as you type against the rules CommCare applies. Illegal or reserved keys are rejected, so Nova refuses them before they can reach a push.

An entry applies to every level by default. Narrow it when only some kinds of place have that information. You can also require a value or give the entry a closed list of accepted values. Nova checks existing places before tightening any of those rules, so a catalog edit cannot strand information that no longer fits it.

Nova sends these values with every place it publishes, but it cannot define the fields themselves: that page on CommCare HQ takes no API. Nova lists what to add and where after you publish. Until a field is defined over there, its value still arrives, as loose data that nothing on CommCare HQ can validate or filter on.

Places

The places themselves — your actual districts and facilities. Unlike levels, these are data, so you can add thousands. Publishing sends them to your CommCare HQ project space, working down from the top so each place can name the one above it.

Each place sits at a level. A root place has no containing place; every other place sits inside a compatible place above it. A place may skip a level — if some regions run districts and some do not, a facility can hang directly off its region. Nova does not make you invent a placeholder district, because a made-up place is worse than an absent one: expressions that look for the district would find the fake one and give a confident wrong answer, where a genuine gap gives an honest empty one.

Two things to know if you plan to publish. CommCare HQ will not take a place that skips a level, so Nova stops before sending anything and names each place, and you either add the missing rung on CommCare HQ or move the place. And CommCare HQ needs the places under one parent to have different names, where Nova only asks their codes to differ, so two clinics called "North" in the same district stop a publish until one is renamed. Both are checked before any place is sent, so a publish never leaves half a tree over there.

One owner rule stays closed at export: a particular place, which names that place by Nova's own id rather than the one CommCare HQ gave it, so the rule would match nobody over there. A place beneath the current case owner exports on every mode, because it travels as level codes and the case's own owner.

Every place gets a code when you create it, and that code never changes — renaming a place leaves it alone. The code is what bulk uploads and CommCare use to identify the place, so it has to stay put even as the name changes. It is also what Nova matches on when it publishes: a place whose code is already taken on the project space by something Nova did not make stops the publish, and you choose whether that one is yours.

Open a place to edit its name, its ID in another system, where it sits, and the place-information values that apply at its level. Moving a place keeps its code and its whole subtree; Nova offers only destinations that preserve the level hierarchy.

Archiving

Places are archived rather than deleted, because deleting one would strand the cases it owns with no way back. Archiving stops Nova sending that place when you publish, and leaves the one already on CommCare HQ exactly where it is: its API offers no way to archive or delete a place, so Nova names it rather than pretending. Its code stays reserved over there either way.

Archiving a place also archives everything under it. Nova shows complete counts and a short name preview before you confirm; the confirmation itself is bound to the complete hidden plan, so a changed descendant or assignment forces a fresh review:

• how many places go with it;
• which personas stop working there — their next remaining place becomes their main one, and a persona left with nowhere carries no location information at all;
• how many cases are owned there. Those cases do not move. They stay where they are, still linked to the archived owner. A persona the archive displaced no longer receives them in Preview, because delivery follows the worker's current assignments.

If an archive would break a fixed-place or next-level case-owner rule, Nova names that form and blocks the archive. Change the owner rule first; silently removing it or leaving it without a destination would change where future cases go.

Bringing a place back also restores the path to it, since a place is unreachable while anything above it is archived. It does not restore assignments — those are your edits now, and Nova will not overwrite a deliberate change with the memory of an older one.

Assigning a persona

A persona's places are set on App setup → Users & personas, under Where they work. The first place in the list is their main one; use Make main to promote another.

A persona assigned nowhere carries no location information in Preview. That is the same empty session shape CommCare gives an unassigned worker. When you make workers from your personas after a publish, each account carries these same assignments onto the project space.

Sending a case to a place

On a form's Case changes screen, Who owns the case can point to a place in two safe ways:

• A particular place stores that place's identity. Renaming the place does not break the rule. The place must own cases, and every assigned persona must be able to carry it in their address book.
• A place beneath the current case owner finds a place at a chosen level by following the organization's built-in lineage. This is useful for queues such as a facility's private data bucket: the selected case belongs to the facility, and the new case goes to the bucket under that same facility.

These are structural references, not pasted expressions. Nova updates their printed names from the current organization and refuses a rule whose level or place can no longer work. Case flow still decides whether the destination owns cases; address-book visibility decides whether a worker can name it. One does not substitute for the other. Both work in Preview. A place beneath the current case owner also publishes and exports: the rule names levels by their codes, which mean the same thing on both sides once the project space's levels carry them. Levels themselves are made by hand on CommCare HQ, and a publish checks for them and names any that are missing in its setup notes. A particular place works in Preview only for now, because the exported rule would name the place by Nova's own id, which the project space does not know; Nova refuses the export and says so, and pointing the rule at a place beneath the current owner is the way through.