Before running any workflow in Ecoscope, you must first configure at least one data source. Data sources provide the input data that workflows query, process, and visualize.

Without a configured data source, workflows cannot retrieve data and therefore cannot be executed.
 

What Is a Data Source?

In Ecoscope, a data source represents a connection to an external system that contains operational data such as GPS observations, patrol logs, or event records.

Data sources can be configured in Ecoscope Web or Ecoscope Desktop, depending on how workflows are being run.
Once connected, data from the source becomes available to applicable workflows (such as Subject Tracking, Events, or Patrols). Workflows then use this data to generate maps, charts, and summary metrics.
 

Supported Data Sources

The available data sources currently differ slightly depending on whether you are using Ecoscope Web or Ecoscope Desktop.

Ecoscope Web

Currently supports:

• EarthRanger
• Google Earth Engine

Future compatibility is planned for additional platforms such as SMART and other conservation data providers.

Ecoscope Desktop

Ecoscope Desktop supports additional integrations designed for more advanced workflows and offline environments, including:

• EarthRanger
• SMART
• Google Earth Engine
   

Desktop integrations allow users to configure connections locally and may require importing credentials or configuration files instead of entering them directly into a form.

Connecting a Data Source

The process for adding a data source varies slightly between Ecoscope Web and Ecoscope Desktop.

Connecting an EarthRanger Data Source (Web)

To connect your EarthRanger instance in Ecoscope Web:

1. Navigate to the Data Sources tab in the top navigation bar.
2. Click Connect Data Source.
3. Fill in the required connection details.
4. Click Save to validate and store the connection. 

Required Fields

Data Source Name
A unique name for the connection (e.g., Serengeti_ER).

EarthRanger URL
The domain of your EarthRanger instance
(e.g., https://<yourdomain>.pamdas.com).

Username
Your EarthRanger username.
 Note: ⚠️ This is not your Ecoscope username.

Password
Your EarthRanger password.
 Note: ⚠️ This is not your Ecoscope password.

If the connection is successful, the data source will appear in the Data Sources list view.

Tip:
If the connection fails, double-check that you entered your EarthRanger credentials rather than your Ecoscope login. 

Connecting a Google Earth Engine Data Source (Web & Desktop)

Google Earth Engine connections work the same way whether you're on Ecoscope Web or Ecoscope Desktop. Before connecting, you'll need a Google Cloud service account with Earth Engine access and a downloaded JSON private key.

Step 1: Create a service account in Google Cloud

1. Confirm the Earth Engine API is enabled on your Google Cloud project (register at code.earthengine.google.com/register if you haven't already).
2. Open Google Cloud Console and navigate to IAM & Admin → Service Accounts.
3. Click + Create Service Account.
4. Provide a name and (optional) description for the account.
5. Under Permissions, assign an Earth Engine role — Resource Admin or Resource Writer for most workflows, Resource Viewer for read-only access to public data.
6. Click Done to finish creating the account, and note the auto-generated service account email (ends in .iam.gserviceaccount.com).
   
    

Step 2: Generate a private key

1. Open the newly created service account.
2. Navigate to the Keys tab.
3. Click Add Key → Create New Key.
4. Select JSON as the key type.
5. Click Create — a .json file downloads to your computer. This is the only copy; store it securely.

This file contains the service account email, the project ID, and the authentication credentials Earth Engine needs.

Step 3: Connect the data source in Ecoscope

In Ecoscope Web or Desktop, go to Data Sources → Connect Data Source (Web) or Data Sources and select the type (Desktop), then choose Google Earth Engine and fill in:

• Data Source Name — A label you'll recognize later.
• Private Key — Browse and select the .json key file you downloaded.
• Service Account Email — Ends in .iam.gserviceaccount.com.
• Project ID — Your Google Cloud project ID.

Using the connection in a workflow

Any workflow with a "Connect to Earth Engine" section (for example the NDVI workflow) will offer this data source in the dropdown.

Connecting Data Sources in Ecoscope Desktop

Data sources in Ecoscope Desktop are configured locally within the application.

Unlike Ecoscope Web, Desktop integrations may require importing credential files or specifying configuration parameters depending on the source. Desktop also allows connections to additional data sources designed for more advanced workflows or environments where cloud services may not be available.

The general process is:

1. Open the Data Sources section in Ecoscope Desktop.
2. Select the type of data source you want to configure.
3. Provide the required credentials or configuration files.
4. Save the configuration to make the data source available to workflows.

The specific setup steps vary depending on the data source.

EarthRanger (Desktop)

EarthRanger data sources allow Ecoscope Desktop workflows to access tracking, event, and patrol data from your EarthRanger site. Depending on your site, you connect using EarthRanger sign-in or your EarthRanger username and password.

To configure an EarthRanger data source:
1. Open the Data Sources section in Ecoscope Desktop.
2. Select EarthRanger as the data source type.
3. Enter your EarthRanger URL (the part before .pamdas.org) and a Data Source Name.
4. Complete the connection using one of the methods below.
 

With EarthRanger sign-in
 

Some EarthRanger sites require an additional authentication multi-factor authentication step. If your site uses this, after you click Return to Ecoscope, Ecoscope Desktop shows an Additional authentication required message and you will need to click a button to open the EarthRanger sign-in page again. Sign in a second time and repeat steps 3 and 4 to finish connecting.

 

1. Click Next. Your web browser opens the EarthRanger sign-in page.
2. Sign in with your EarthRanger account. If you're already signed in, this step is skipped.
3. Click Accept to allow Ecoscope Desktop to access your EarthRanger account.
4. Click Return to Ecoscope, then click Done in Ecoscope Desktop.
 

With username and password

1. Under EarthRanger Account Login, enter your EarthRanger username and password.
2. Click Connect.
Credentials entered this way are not validated during setup. If they are incorrect, errors will only appear when a workflow is run.
Once connected, the EarthRanger data source will be available when configuring workflows that support EarthRanger data.
 

SMART (Desktop)

SMART data sources allow Ecoscope Desktop workflows to access patrol and event data stored in a SMART database.

To configure a SMART data source:

1. Open the Data Sources section in Ecoscope Desktop.
2. Select SMART as the data source type.
3. Provide the required SMART connection details.
4. Save the configuration.

Once saved, the SMART data source will be available when configuring workflows that support SMART data. 

Viewing and Managing Existing Data Sources
 

All configured data sources appear in the list view under the Data Sources tab. Each row displays key information:

• Data Source Name – The custom name you gave the connection.
• Domain – The URL or domain of the connected EarthRanger instance.
• Connection Type – Currently limited to EarthRanger, with more to come.
• Created At – Timestamp of when the connection was added.
• Updated At – Timestamp of the last successful update or reconfiguration.
   

When is an update required? 

On Ecoscope Web, authentication tokens between Ecoscope and your EarthRanger instance may expire over time.
When this happens, you will be prompted to Reconnect the data source before running new workflows.

On Ecoscope Desktop, if you are using EarthRanger IdP, tokens may expire over time.
When this happens, you will be prompted to Reconnect the data source before running new workflows.

This is a normal security measure that ensures connections remain authenticated and secure.

On Ecoscope Desktop, if you are using an EarthRanger data source authenticated with a username and password, authentication tokens are created on-the-fly when they are needed and held only in-memory, so reconnect flows do not apply.