Skip to main content

EarthRanger Setup Instructions

This guide walks you through connecting your EarthRanger instance to Safora. Once complete, Fence Shield observations and events will flow into your dashboard.

If you haven't already, read the Overview to see what data appears and how events behave.

Prerequisites​

Before you begin, make sure you have:

RequirementNotes
An EarthRanger instanceYour organisation's live or sandbox environment
Admin access in EarthRangerA user who can create accounts and assign permissions
A Gundi accountGundi is EarthRanger's sensor integration platform

If you're missing any of the above, check with your EarthRanger administrator or refer to EarthRanger's documentation.

Setup overview​

There are five steps. Each builds on the previous one:

  1. EarthRanger account and permissions
  2. Gundi connection setup
  3. Source provider
  4. Event types
  5. Subject group

1. EarthRanger account and permissions​

Safora needs a dedicated EarthRanger user and API token to send observations and events to your instance.

Create the Safora user​

  1. Open your admin page at your-domain.pamdas.org/admin.

  2. Go to Home > User Accounts > Users > Add User.

  3. Set Username to safora.

  4. Assign these permissions exactly:

    • Administer Sources
    • Administer Subjects
    • Admin Logistics Event Permissions
    • Admin Monitoring Event Permissions
    • Admin Security Event Permissions
    • Observation APIs

  5. Click Save.

EarthRanger user permissions for the Safora account

Create a DAS access token​

  1. Go to Home > DAS Configuration > DAS Access Tokens > Add DAS Access Token.
  2. Set Date to 2099-12-31 and click Now for the time.
  3. Set Scope to exactly read write.
  4. Generate a 40-character alphanumeric token. You can use a random alphanumeric generator (length 40, quantity 1).
  5. Set User to safora, the user you created above. Do this by pressing the magnifying glass and searching for safora.
  6. Copy the token and keep it somewhere safe. You will need it in the next step. Then click Save.
EarthRanger DAS access token configuration

2. Gundi connection setup​

Gundi receives data from Safora and formats it for EarthRanger.

Create the connection​

  1. In Gundi, go to Connections > Create Connection.
  2. Select Provider: API
  3. Configure Provider: set Connection Name to Safora integration
  4. Create New Destination
  5. Connect Destination: Create New Destination
  6. Now fill in the following:
    • Name: a label for your EarthRanger instance (e.g. your reserve name)
    • Workspace: Select your desired workspace
    • Site URL: your official instance name, without .pamdas.org
    • Auth: keep Token
    • Token: paste the 40-character DAS access token from step 1
  7. Click Save.
Gundi connection destination configuration
  1. Click Next. You will land on the connection overview page.

Share credentials with Safora​

  1. Under How to Connect, copy the API Key using the copy icon next to the eye icon.
  2. Copy the connection ID from the URL: https://gundiservice.org/connections/{connection-id}/provider. Save it somewhere as you will need it for the next step.
Gundi connection overview showing API key and connection ID in the URL

Send the API Key to the Safora team at info@safora-tech.com together with your EarthRanger instance name so we can complete the integration on our side. Treat the API key like a password: do not share it publicly.

3. Source provider​

The source provider tells EarthRanger how to display Fence Shield measurement data, right from your dashboard.

  1. Go to Home > Observations > Source providers > Add source provider.

  2. Set Natural key to:

    gundi_api_push_{connection-id}

    Replace {connection-id} with your Gundi connection ID. For example:

    gundi_api_push_8d8e7483-1ea3-4068-9513-8f09ed7f86fe

  3. Set Display name to Safora.

  4. Click Show under Subject Details Configuration.

  5. Click Show under Advanced transformation rules and paste exactly:

[
  {
    "default": true,
    "dest": "fence_voltage",
    "label": "Fence Voltage",
    "source": "fence_voltage",
    "units": "kV"
  },
  {
    "default": false,
    "dest": "device_battery_soc",
    "label": "Battery Charge",
    "source": "device_battery_soc",
    "units": "%"
  }
]
  1. Click Save.
EarthRanger source provider configuration for Safora

4. Event types​

Create the three event types Safora sends. Add them one at a time under Home > Activity > Event Types > Add Event Type.

Low Fence Voltage​

FieldValue
DisplayLow Fence Voltage
Valuesafora_low_fence_voltage
CategoryMonitoring
Icon Overridefence_voltage_rep
Ordernum7.0
Default priorityAmber

Schema (paste exactly):

{
  "schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Low Fence Voltage",
    "type": "object",
    "properties": {
      "fence": { "type": "string", "title": "Fence" },
      "voltage": { "type": "string", "title": "Voltage" }
    }
  },
  "definition": ["fence", "voltage"]
}

Click Save and add another.

EarthRanger Low Fence Voltage event type configuration

Low Battery​

FieldValue
DisplayLow Battery
Valuesafora_low_battery
CategoryLogistics
Icon OverrideLow_battery_rep
Ordernum50.0
Default priorityAmber

Schema (paste exactly):

{
  "schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Low Battery Alert Schema",
    "description": "Low battery percentage detected by Fence Shield device.",
    "type": "object",
    "properties": {
      "fence": { "type": "string", "title": "Fence" },
      "charge": { "type": "number", "title": "Charge (%)" }
    }
  },
  "definition": ["fence", "charge"]
}

Click Save and add another.

Tamper Detected​

FieldValue
DisplayTamper Detected
Valuesafora_fence_tamper
CategorySecurity
Icon OverrideThreats_rep
Ordernum3.0
Default priorityRed

Schema (paste exactly):

{
  "schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Tamper Detected",
    "description": "Tamper detected by Fence Shield device.",
    "type": "object",
    "properties": {
      "fence": { "type": "string", "title": "Fence" }
    }
  },
  "definition": ["fence"]
}

Click Save.

5. Subject group​

Last step. The subject group lets you show or hide all Fence Shield sensors on the map from one place.

  1. Go to Home > Observations > Subject groups > Add subject group.
  2. Set Name to Fence monitors.
  3. Make sure Visible is checked.
  4. Click Save.
EarthRanger subject group configuration for Fence monitors

When you connect new devices, add them under Subjects. Note that they will only appear in EarthRanger after their first observation is sent.

To toggle visibility on the map, go to Map Layers > Subjects and check or uncheck Fence Monitors. See the Overview for details.

You're all set​

Once Safora has your Gundi API key and instance name, we will wire up the integration on our side. After the first devices send data, you should see observations and events appear in EarthRanger.

Questions along the way? Reach us at info@safora-tech.com.