The Integrator

Connect mWater to everything

The Integrator provides two powerful ways to connect mWater with external systems:

- AI Agentic Imports: Use AI assistance to automatically import data from external APIs into mWater tables. The AI agent helps you write the code needed to fetch, transform, and map external data with no programming experience required.
- Export Integrations: Create shareable API endpoints that expose your mWater data in formats like CSV, JSON, or GeoJSON. Perfect for feeding dashboards, external tools, or other systems that need access to your mWater data.

Both features are accessible from the Integrations page in the mWater portal. This capacity aims to make connecting mWater with other systems vastly easier and in reach for the great majority of users.

This development was funded by UNICEF MG MERL

An example AI-assisted import integration

AI Agentic Imports

What are AI Agentic Imports?

AI Agentic Imports use artificial intelligence to help you create integrations that automatically pull data from external APIs into your mWater tables.

With the Importer you don't need to be a programmer to build integrations. You can just describe what you want to import, and the AI does the heavy lifting.

The AI agent:

- Understands your requirements through natural language
- Inspects external APIs to understand their structure
- Writes JavaScript code to fetch and transform the data
- Maps data to your mWater table schemas
- Handles authentication securely
- Supports incremental imports to only fetch new or changed data

Creating an Import Integration

1. Navigate to Import Integrations
- Go to the Integrations page
- Click "Manage import integrations"

2. Start a New Import
- Click "New Import Integration"
- Select the tableset where you want to import data
- Choose the data source type:
- API: Pull data from an external API on a schedule
- Webhook: Receive data pushed to mWater by an external system

3. Describe What You Want to Import
- In plain language, tell the AI what data you want to import
- Examples:
- "Import water level readings from our sensor API at https://api.example.com/sensors"
- "Import daily rainfall data from the national weather service API"
- "Import transaction records from our payment system at https://api.openaq.org/v3/locations?parameters_id=2&limit=1000"
- Include details like:

The API endpoint URL
What kind of data it provides
How often it updates
Any authentication requirements

4. Let the AI Agent Work
- The AI agent will:
1. Inspect the API to understand its structure
2. Ask clarifying questions if needed (e.g., "Which table should this data go into?")
3. Write the import code automatically
4. Test the code to ensure it works
5. Show you a preview of what will be imported

5. Review and Refine
- Review the AI's work:
- Check the code it generated
- Verify the data mapping looks correct
- Test with sample data
- Provide feedback if needed:
- "Change the date format"
- "Add a filter to only import records from the last 30 days"
- "Map this field to a different column"

6. Configure Secrets
- If the API requires authentication, the AI will identify what credentials are needed
- Enter API keys, tokens, or other credentials securely
- These are encrypted and stored safely and never exposed in logs or code

7. Set Up Scheduling
- Choose how often the import should run:
- Manual only Run imports on-demand
- Daily: Run at a specific time each day
- Weekly: Run on a specific day and time
- Monthly: Run on a specific day of the month
- Set the time in UTC

8. Save and Activate
- Click Save to create the integration
- The import will run automatically according to your schedule
- You can also trigger manual runs anytime

How the AI Agent Works

The AI agent uses a conversational approach to build your integration:

Understanding Phase
- Reads your description
- Identifies the API endpoint and data structure
- Determines what tables and columns are needed
Exploration Phase
- Fetches sample data from the API (if accessible)
- Analyzes the response structure
- Identifies data types and formats
Code Generation Phase
- Writes JavaScript code to:
  - Authenticate with the API
  - Fetch data (handling pagination if needed)
  - Transform data to match your mWater schema
  - Handle errors gracefully
Mapping Phase
- Maps external fields to mWater table columns
- Handles data type conversions
- Creates new tables if needed (with your approval)
Testing Phase
- Executes the code in a safe sandbox environment
- Shows you sample results
- Validates that data will import correctly
Refinement Phase
- Incorporates your feedback
- Adjusts code based on your requirements
- Re-tests until you're satisfied

You're in Control:

Review all code before it runs
Edit code manually if you prefer
Ask the AI to make changes
Test as many times as needed

Scheduling and Automation

Once your import integration is set up, it runs automatically:

Schedule Options:

Manual: Only runs when you click "Run Now"
Daily: Runs once per day at a specified UTC time
Weekly: Runs once per week on a specified day and time
Monthly: Runs once per month on a specified day

Incremental Imports: The AI agent can set up incremental imports that only fetch new or changed data:

Tracks state between runs (e.g., last sync timestamp, last record ID)
Only requests data since the last import
Reduces API load and import time
Prevents duplicate data

Monitoring:

Check the import status on the Import Integrations list
View last run time and success/failure status
See how many rows were imported
Review error messages if imports fail

Import Best Practices

Start Simple: Begin with a basic import, then add complexity
Test First: Always test with sample data before scheduling regular imports
Use Incremental Imports: When possible, configure imports to only fetch new data
Secure Credentials: Never share API keys or tokens, use the secrets feature instead
Monitor Regularly: Check import status periodically to catch issues early
Handle Errors: Review error messages and adjust code as needed
Document Your Integrations: Add clear descriptions so others understand what each integration does
Respect API Limits: Be aware of rate limits on external APIs
Choose Appropriate Schedules: Don't import more frequently than the source data updates
Validate Data: Spot-check imported data to ensure it's correct

Export Integrations

What are Export Integrations?

Export Integrations create secure, shareable URLs that allow external systems to download your mWater data in various formats (CSV, JSON, or GeoJSON).

You control:

- Which data is exposed (by selecting tables, columns, and filters)
- How it's formatted (CSV for spreadsheets, JSON for APIs, GeoJSON for mapping tools)
- Who can access it (through role-based permissions)
- What parameters can be used to filter the data dynamically

Creating an Export Integration

1. Navigate to Integrations

Go to the Integrations page in the mWater portal
Click "Manage export integrations" or go to /integrations/export

2. Create a New Export

Click "New Export Integration"
Fill in the basic information:
- Name: A descriptive name for your export (e.g., Water Point Locations for Dashboard)
- Description: Optional details about what this export provide.

3. Select your Data Source

Choose the table you want to export from
This can be any table in your mWater database (sites, custom tables, survey responses, etc.)

4. Define Columns

Add columns to include in the export
Each column can be:
- A direct field from the table
- A calculated expression (e.g., formatted dates, concatenated text, computed values)
Give each column a clear label that will appear in the exported file

5. Set Up Filters (Optional)

Add filters to limit which rows are exported
Use the expression builder to create complex filter conditions
Filters can reference variables for dynamic filtering

6. Configure Variables (Optional)

Variables allow callers to filter the export via URL parameters

For example, create a region variable so users can request data for a specific region:

https://api.mwater.co/integrations/export/abc123.csv?region=North⁠
Supported variable types:
- Text, Number, Boolean, Date/DateTime, Enum (choice)

7. Set Ordering (Optional)

Define how rows should be sorted in the export
Add multiple sort criteria if needed

8. Configure Permissions

Set which users or groups can view and edit this export integration
Note: Anyone with the export code can download the data, so use permissions to control who can see the integration configuration

9. Set Limits

Configure a maximum number of rows to prevent accidentally exporting huge datasets
Default is 10,000 rows

10. Save and Test

Click Save to create your export integration
Use the Preview feature to test your export before sharing the URL
Copy the export URL to share with external systems

Using Export URLs

Once created, each export integration has a unique URL that follows this pattern:

https://api.mwater.co/integrations/export/{code}.{format}

Parameters:
- {code}: The unique code for your export integration (shown in the UI)
- {format}: One of csv, json, or geojson

Examples:

Download as CSV
https://api.mwater.co/integrations/export/abc123def456.csv

Download as JSON
https://api.mwater.co/integrations/export/abc123def456.json

Download as GeoJSON (requires geometry columns)
https://api.mwater.co/integrations/export/abc123def456.geojson

With variable parameters
https://api.mwater.co/integrations/export/abc123def456.csv?region=North&start_date=2024-01-01

Integration with External Tools:

- Google Sheets: Use IMPORTDATA() function or a script to periodically fetch the CSV URL
- Power BI / Tableau: Connect directly to the JSON or CSV endpoint
- Custom Coded Dashboards: Use JavaScript fetch() to load JSON data
- Mapping Tools: Use GeoJSON format for geographic visualizations

Export Best Practices

1. Name Clearly: Use descriptive names that indicate what data the export contains
2. Document Variables: If you use variables, document what values they accept
3. Set Reasonable Limits: Prevent accidental large exports that could impact performance
4. Test Regularly: Verify your exports still work after schema changes
5. Monitor Usage: Check download statistics to see how often your exports are used
6. Use Filters: Always filter to only export necessary data but don't export entire tables unless needed
7. Consider Permissions: Remember that anyone with the code can access the data, so protect the code accordingly. You can regenerate it if needed.

Common Integrator Use Cases

Use Case 1: Importing Sensor Data

Scenario: You have IoT sensors that measure water levels and send data to an API. You want this data in mWater for analysis.

Solution: Use AI Agentic Import to:

Connect to your sensor API
Import readings into a custom table
Run daily to keep data current
Map sensor IDs to your water point sites

Steps:

Describe: "Import water level readings from https://api.sensors.com/readings"
Let AI inspect API and create integration
Map sensor_id to water_point_id
Schedule daily imports
Create visualizations in mWater using the imported data

Use Case 2: Exporting Site Data for External Dashboard

Scenario: You have a dashboard in another tool that needs to display your water point locations.

Solution: Create an Export Integration that:

Exports from the entities.water_point table
Includes columns: name, location (lat/lng), status, last inspection date
Formats as GeoJSON for easy mapping
Filters to only active water points
Updates automatically as your data changes

Steps:

Create export integration with water point table
Add relevant columns
Add filter: status = 'active'
Share the GeoJSON URL with your dashboard tool

Use Case 3: Syncing with External Database

Scenario: Your organization uses another system for financial data, but you want to combine it with mWater survey data for reporting.

Solution: Create an import that:

Connects to the external financial API
Imports transaction records into a custom table
Links transactions to sites or surveys via IDs
Runs weekly to stay synchronized

Use Case 4: Webhook Integration

Scenario: An external system needs to push data to mWater in real-time (e.g., payment confirmations, form submissions).

Solution: Use Webhook Import Integration:

Create a webhook endpoint in mWater
Share the webhook URL with the external system
Configure the AI agent to transform incoming webhook payloads
Data imports automatically when the external system sends it

Getting Help

If you encounter issues:

Check the error message in the import/export details
Review the code (for imports) or configuration (for exports)
Test with sample data to isolate the problem
Contact mWater support info@mwater.co with:
- Integration name and ID
- Error message
- Steps to reproduce

Troubleshooting

Import Integration Issues

Problem: Import fails with authentication error

Check: API credentials may have expired or changed
Solution: Update secrets in the integration settings

Problem: Import runs but no data appears

Check: Data mapping may be incorrect
Solution: Review the code and test with sample data

Problem: Import creates duplicate rows

Check: Incremental import may not be configured correctly
Solution: Review state tracking fields and ensure unique keys are set

Problem: AI agent doesn't understand my request

Check: Description may be too vague
Solution: Provide more details: API URL, data structure, authentication method

Problem: Import code has errors

Check: External API structure may have changed
Solution: Ask AI agent to re-inspect API and update code

Export Integration Issues

Problem: Export returns empty results

Check: Filters may be too restrictive
Solution: Review filter expressions and test with preview

Problem: Export URL returns 404

Check: Verify the export code is correct
Solution: Copy the code directly from the integration page

Problem: Export is slow or times out

Check: You may be exporting too much data
Solution: Add filters, reduce columns, or lower the max limit

Problem: Variables not working in URL

Check: Variable parameter names must match exactly
Solution: Use the URL preview feature to see correct parameter names

info@mwater.co - Last updated 2026/2/22