Skip to content

EarthRanger Action Runner

A Gundi v2 integration that pulls events and subject observations from an EarthRanger (ER) site on a schedule and forwards them to Gundi, which routes them onward to any configured destinations (for example, a C-more instance).

It is pull-based: actions are triggered on a schedule via GCP PubSub, fetch data from the ER API, transform it into the Gundi schema, and send it through the Gundi API.

EarthRanger site  →  pull action  →  transform to Gundi schema  →  Gundi API  →  destinations

The four actions

Action What it does
auth Validates the configured EarthRanger credentials (token or username/password).
pull_events Pulls ER events — plus their note and field updates — and sends them to Gundi as events and event updates.
pull_observations Pulls tracking observations for the configured ER subject groups and sends them to Gundi as observations.
show_permissions Diagnostic. Lists the event categories and subject groups the configured account can access — and the UUIDs the pull actions need.

How to read these docs

  • Architecture — the runtime: how a PubSub message becomes an action execution, config caching, scheduling, self-registration.
  • Actions — what each action does and every config field it accepts.
  • Data flow — how ER events and observations are transformed into the Gundi schema, including the note/field → event-update path.
  • State & scheduling — per-event state, watermarks, and the resumable observation backfill.
  • Configuration reference — every field of every config model in one table.
  • Local development — run the service locally and run the tests.
  • Contributing — how to add a new action.

Integration type slug

The canonical Gundi integration-type slug for this runner is earth_ranger (with an underscore). It matches gundi_core.schemas.v1.DestinationTypes.EarthRanger and the fixtures across cdip-routing and the gundi-integration repos. Always use earth_ranger when setting INTEGRATION_TYPE_SLUG, running python app/register.py --slug …, or referencing this integration type elsewhere — the wrong slug breaks registration.

Note

An earthranger type without the underscore existed historically as a registration accident and is being cleaned up. See PR #13.