Skip to content

Configuring the Africam integration

All settings live on the Africam integration's single action, process_new_events, configured in the Gundi portal. The action runs on a * * * * * crontab — once a minute, automatically.

← Overview

Action settings

Field Required Default Description
Africam API URL — https://ranger-media.africam.com Base URL of the Africam API. Events are POSTed to {url}/events/webhook.
Africam API Token yes — Bearer token for Africam. Stored as a secret (password field).
Event Types — ["wildlife_sighting"] EarthRanger event-type slugs to forward. Anything not in this list is ignored. Once an EarthRanger destination is attached to the route, each item offers that site's event types as a dropdown (the destination's list_event_types reference action); you can still type a slug by hand.
Lookback Hours — 1 (1–168) How far back the first run fetches, and the maximum any later run reaches back. The window normally continues from the previous run, but never further back than this.
Africam Event URL Template — https://ranger-media.africam.com/gallery/{africam_event_id} Format string for the gallery URL written back to EarthRanger. Must start with https:// and contain {africam_event_id} — both are validated when you save.
Start Datetime — empty Must not be in the future. Only used by Force Run From Start Datetime.
Force Run From Start Datetime — off Each time it is switched on, the next run fetches all configured event types from Start Datetime once, ignoring the saved watermarks and the Lookback Hours cap; after that, normal incremental fetching resumes. Switch it off and on again (or change Start Datetime) to repeat.

Where the EarthRanger credentials come from

EarthRanger access is not configured on this action. At runtime the runner reads the connection's destination integrations: each one's base URL plus the token from its Authentication action config. Every EarthRanger destination on the connection is processed on every run.

If the connection has no destinations, or a destination has no token in its auth config, the whole run fails — see Troubleshooting.

The incremental fetch window

Each EarthRanger destination keeps one watermark per configured event type in the runner's Redis state (keyed by the destination's base URL):

  • First run for a type (no watermark yet, including a slug you just added to Event Types): fetch that type's events updated in the last lookback_hours.
  • Every later run: fetch each type's events updated since the last run that fetched that type, but never further back than lookback_hours. A stale watermark (for example after a long outage) is capped rather than triggering an unbounded backfill. When that happens the run logs a one-off WARNING naming the capped types and the skipped range, so you can backfill by editing the affected events (see Troubleshooting).
  • A type that stops resolving (renamed or disabled in EarthRanger) keeps its watermark while the other types carry on. Once the slug resolves again its backlog is picked up from where it left off, up to lookback_hours.

Types whose watermarks are equal are fetched in a single EarthRanger call, so in the steady state this still costs one request per destination per minute.

Because the filter is updated since, edits to older events re-fetch them — and the already-processed check (below) keeps them from being re-forwarded.

What gets forwarded, exactly

From each fetched event, the runner keeps only events whose type is in Event Types and which do not already have africam_event_url in their details, then POSTs to POST {africam_api_url}/events/webhook:

{
  "event_type": "event_update",
  "data": {
    "id": "<er-event-id>",
    "event_type": "wildlife_sighting",
    "title": "...",
    "location": {"latitude": -1.4061, "longitude": 35.1425},
    "event_details": {"species": "white rhino", "count": 3}
  }
}

Africam replies with {"status": "updated", "eventId": "<uuid>"}. The runner formats Africam Event URL Template with that eventId and patches the EarthRanger event's details:

{"event_details": {"...existing details...": "...", "africam_event_url": "https://ranger-media.africam.com/gallery/<uuid>"}}

A sanitized Postman collection with this exact request lives in the repo — handy for testing the Africam endpoint with your own token.

Event-type slugs are resolved per site

The EarthRanger API filters events by event-type ID, not slug, so each run resolves your configured slugs to IDs per site. A slug that doesn't exist on a site is skipped with a warning (throttled to once an hour per site); if none of your slugs exist on a site, that site's fetch is skipped entirely — the runner never falls back to fetching all events.

← Overview · Troubleshooting

Re-fetching a time range (resetting the watermarks)

The action remembers, per event type, when it last fetched, and each run continues from there. To make it re-read a range (for example after events were missed while a slug was misspelled, or after a stall):

  1. Set Start Datetime to the beginning of the range you want re-read (it cannot be in the future).
  2. Turn Force Run From Start Datetime on and save.
  3. Wait for the next run (within a minute). The Activity Log shows one warning naming the start time, and that run fetches every configured type from it. Events that already carry an africam_event_url are skipped, so only events never forwarded are sent to Africam.
  4. That is it. The forced fetch happens once per switch-on: later runs continue incrementally from the forced run, even if the toggle stays on. To repeat it, switch the toggle off and save, then on and save again, or change Start Datetime.

The Lookback Hours cap does not apply to a forced run, so choose a Start Datetime that matches the range you actually need; a very old start on a busy site means one large fetch. Each EarthRanger destination on the connection applies the forced run independently.