Skip to main content

External Integrations

info

AquaGen API integrates with multiple external services for telemetry, AI, notifications, and analytics.

Azure IoT Hub​

Used for reliable telemetry ingestion from IoT edge devices (flow meters, quality sensors, energy meters).

Configuration: IOTHUB-CONNECTION-STRING in Azure Key Vault.

Device telemetry is received by the IoT Hub, processed by the batch processing pipeline, and stored in the devices_data Cosmos DB container.

# config.py
IOTHUB_CONNECTION_STRING = smi.get(SecretName.IOTHUB_CONNECTION_STRING)
note

Device Management: New devices are registered in the industries container under the units array with their unitId, standardCategoryId, and metadata.

Firebase​

Used for two features: push notifications and file storage.

Firebase Cloud Messaging (Push Notifications)​

Required secrets:

  • FIREBASE-CREDENTIALS — Firebase service account JSON (stored as dict in Key Vault)
  • FIREBASE-STORAGE-BUCKET — Firebase storage bucket name

FCM tokens are stored in each user's document (fcmTokens array). The FirebaseChannel in AlertsProcessor sends push notifications to all registered device tokens for alert recipients.

Firebase Storage​

Generated reports can be uploaded to Firebase Storage for mobile app access. URLs are included in notification payloads.

SMTP / Email​

Used for automated report delivery and alert email notifications.

Required secrets (via Key Vault):

  • SMTP host, port, username, password (managed as Key Vault secrets)

The send_mail_service.py handles email composition and sending. Automated reports are attached as PDF/XLSX/CSV files.

SMS Gateway​

SMS notifications for alerts are sent via a configured SMS gateway.

Required secrets:

  • SMS-API-ENDPOINT — SMS gateway API URL
  • SMS-USER-ID — Gateway user ID
  • SMS-PASSWORD — Gateway password
  • MSG-TYPE — Message type
  • SMS-VERSION — API version
  • SMS-FORMAT — Response format

Google Chat​

Used for real-time alert notifications to Google Chat spaces via webhooks.

Setup: Configure a Google Chat webhook URL in the industry workspace settings. The gchats.py admin route and GchatsService format and post messages.

Message format: Card messages with alert details, severity indicator, timestamp, and unit information.

Admin API:

POST /api/admin/gchats
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "webhookUrl": "https://chat.googleapis.com/v1/spaces/AAA/messages?key=...",
  "message": "Alert: High water consumption on Main Meter",
  "industryId": "IND001"
}

PowerDrill Analytics​

PowerDrill integration enables advanced analytics queries to be embedded within AquaGen dashboards.

Required secrets:

  • POWER-DRILL-API-KEY — PowerDrill API key
  • POWER-DRILL-USER-ID — PowerDrill user ID

Endpoint: GET /api/user/powerdrill

Google Earth Engine​

Used for water quality satellite data processing.

Required secrets:

  • EARTH-ENGINE-SERVICE-ACCOUNT — Service account JSON (dict format)

Admin endpoint: /api/admin/waterQualitySatellite — processes satellite imagery for water quality analysis.

Azure Application Insights​

All HTTP requests, exceptions, dependencies, and custom events are logged to Application Insights.

Configuration: APPLICATIONINSIGHTS_CONNECTION_STRING (environment variable, falls back to Key Vault APPLICATION-INSIGHTS).

The FlaskMiddleware (from opencensus) wraps the Flask app with a ProbabilitySampler at rate 1.0 (100% sampling) and exports to Azure Exporter.

tip

Custom telemetry: Additional custom events can be logged using the App Insights SDK for business-level metrics (report generation counts, alert trigger rates, etc.).

Azure Web PubSub (WebSockets)​

Real-time web notifications are delivered via Azure Web PubSub.

Required secrets:

  • WEBPUB-ENDPOINT — Web PubSub endpoint URL
  • HUB-NAME — Hub name for routing
  • WEBSOCKET-ENDPOINT — WebSocket connection endpoint
  • WEBSOCKET-HUB-NAME — WebSocket hub name
note

The WebChannel in AlertsProcessor sends messages to the industry's Web PubSub channel. Connected web clients receive real-time alert updates without polling.