Koji & Regions¶

This page covers two operator jobs: connecting PoracleWeb.NET to Koji, and setting up regions so the region picker works for your users. The region picker is the part most operators get tripped up on, so the relationship between geofences and regions is laid out carefully with diagrams.

What Koji is doing here¶

Koji is the home for your public geofences — the admin-managed areas everyone can subscribe to. PoracleWeb.NET talks to Koji to:

1. Read the list of public areas (so users can pick them, and the bot can match on them).
2. Read your regions (the folders that group public areas).
3. Write a new public area when an admin approves a user submission.

Private user geofences never touch Koji — they live inside PoracleWeb.NET until (and unless) an admin promotes them.

Connecting PoracleWeb.NET to Koji¶

Set these in your .env file:

Then point your PoracleJS/PoracleNG bot at PoracleWeb.NET's combined feed (a single URL, not Koji) via its geofence-source setting:

// PoracleJS/PoracleNG bot — geofence source
"geofence": {
  "path": "http://poracleweb:8082/api/geofence-feed"
}

That's the whole connection. If Koji is briefly down, PoracleWeb.NET keeps serving the private user geofences and the last-known public ones, so notifications don't stop dead.

How geofences and regions relate in Koji¶

This is the key mental model.

flowchart TD
    Proj[Your Koji project]
    Proj --> CO[colorado
★ REGION — has children]
    Proj --> CA[california
★ REGION — has children]
    Proj --> KC[kansas-city
not a region — no children]

    CO --> DEN[denver]
    CO --> BOU[boulder]
    CA --> SF[san-francisco]
    CA --> LA[los-angeles]

    style CO fill:#1e88e5,color:#fff
    style CA fill:#1e88e5,color:#fff
    style KC fill:#bbb,color:#000

So:

• A region = a parent geofence (a geofence that other geofences are nested under).
• The region itself is hidden from the area picker — you don't subscribe to colorado, you subscribe to denver, which is grouped under Colorado.
• A geofence with no children is not a region — it's just a plain selectable area (kansas-city above).

Here's how PoracleWeb.NET decides what counts as a region:

flowchart TD
    Start[For each geofence in Koji] --> Q{Does any OTHER geofence
list it as its parent?}
    Q -->|Yes| R[It's a REGION
used as a folder]
    Q -->|No| N[Not a region
just a plain area]

Setting up regions (the operator how-to)¶

If your users open the "draw a geofence" dialog and the region dropdown is empty (or only shows "All"), it's because your Koji project has no nesting — every geofence is flat, with no parents. Here's how to create regions:

1. Create a parent geofence in Koji for each region you want — for example a polygon for the whole state of colorado, or a metro area like denver-metro. This is just a normal Koji geofence; nothing special.
2. Nest your public area geofences under it. In Koji, open each child geofence (e.g. denver, boulder) and set its parent to the region geofence (colorado). That parent link is the only thing that makes a region.
3. Done. Reload the geofence page in PoracleWeb.NET (the list refreshes within 5 minutes, or immediately after the next approval). Each parent that now has at least one child shows up as a region, using the parent geofence's display name as the folder label.

flowchart LR
    subgraph S1 [Step 1: make a parent]
        A1[colorado
no children yet,
not a region]
    end
    subgraph S2 [Step 2: nest children under it]
        B1[colorado — now a REGION]
        B1 --> B2[denver]
        B1 --> B3[boulder]
    end
    S1 --> S2

Do you even need regions?¶

No — regions are optional. They are a convenience for grouping public areas and for auto-suggesting a folder when a user draws a shape. If your Koji project is flat and you don't want regions:

• Users can still draw private geofences and use them — the region picker simply hides itself when there are no regions (this fixes the empty-dropdown problem; see Troubleshooting).
• When an admin promotes a geofence, they can leave the region unset, and it becomes an ungrouped public area. You can always organize it into a region later in Koji.

Koji geofence properties (and how they're used)¶

When PoracleWeb.NET promotes a geofence to a public area, it writes a set of properties onto the Koji geofence. If you create or edit geofences directly in Koji, these are the same properties that matter — and getting userSelectable / displayInMatches wrong is the usual cause of a private area leaking into the bot, or a public area never showing up.

There are two groups. The __-prefixed keys are Koji structural directives (they set Koji's own built-in fields). The rest are custom properties that Koji stores on the geofence and passes through to the bot feed.

Structural directives (the __ keys)¶

Custom properties (passed through to the bot feed)¶

For a private user geofence, PoracleWeb.NET never writes any of this to Koji — it serves the geofence from its own feed with userSelectable=false and displayInMatches=false. For an approved (public) geofence, both flags are set to true and the geofence is written into Koji as a normal public area.

What PoracleWeb.NET reads back from Koji¶

What auto-detection does¶

When a user draws a shape, PoracleWeb.NET tries to guess the region by checking which region's outline the drawn shape falls inside (using the center point of the drawing). If it finds a match, it pre-fills the region for the user. This is purely a convenience — the user can change or clear it, and it only works if your regions have outlines (which they do, since they're real Koji geofences).