Every company has places: an office, a few branches, a yard, a shop, a storage container out back. The workspace keeps one list of them, and every module reads the same list. So when your module asks "which yard?", it offers the same yards as HR, Equipment and everyone else, spelled the same way. Please don't build your own list of sites.
What's in the list
A Workspace Admin keeps the list in System settings › Locations. Each location has:
| Detail | Example |
|---|---|
| Name and code | Santa Ana Yard, santa_ana_yard |
| Type | Region, Office, Branch, Yard, Shop, Storage or Other |
| Inside | The location it sits in: West Region › Santa Ana › Yard 2 |
| Address and map spot | Street, city, state, zip, and a map position |
| Phone and notes | Optional |
| Active | Closed places are made inactive, never deleted |
A company with one office has one row. A company with a hundred yards has a hundred. Either way, it's set up once.
Reading locations
Your module can read the list at any time, from a screen or from the server. You get each location with its full path (West Region › Santa Ana › Yard 2), its type, its address and its map position. Parents come before their children, so a nested picker is easy to draw.
- In a picker, offer active locations only.
- When showing old records, read inactive ones too, so a closed yard still shows its name instead of a blank.
Anyone signed in to the workspace can read the list. Only Workspace Admins can add or change locations; modules can't.
Linking a record to a location
Save the location's id on your record, not a copy of its name. Then:
- Your record always shows the current name, even if the location is renamed.
- Every module that links to the same place uses the same id, so reports can line them up by location.
- A closed location still labels your old records, because locations are never deleted.
Have records with an address? The location's map position works with the platform's maps too. See Charts, maps and 3D.
Ask the Module Builder
# For developers: read the list (active only by default)
locs = await list_locations("MY_MODULE", tenant_id)
every = await list_locations("MY_MODULE", tenant_id, include_inactive=True)
# each: id, code, name, location_type, path, depth, address, lat, lng, is_active, ...From a screen, the same list comes from GET /api/v1/locations (add ?include_inactive=true for labels).
Good to know
- Included. Reading locations costs nothing extra.
- No list yet? Ask the Workspace Admin to add their places in System settings › Locations. Your picker fills in by itself.
- Need more detail about a place, like a gate code or a bay count? Keep that in your own module's table, linked by the location's id.
- Rooms or bays can be added as Storage or Other locations nested inside a building or yard.