Map arbitrary broker payloads to and from the Cumulocity domain model using a graphical editor or JavaScript-based mappings.
The Dynamic Mapper connects to external brokers and APIs, subscribes to topics, transforms payloads, and routes data bidirectionally:
- Inbound: Broker -> Cumulocity
- Outbound: Cumulocity -> Broker/API
It supports zero-code mapping, code-based mapping, and AI-assisted mapping suggestions.
- Connect multiple brokers/connectors at the same time
- Create bidirectional mappings between broker payloads and Cumulocity APIs
- Build mappings in a graphical editor or with JavaScript
- Transform payloads with JSONata or JavaScript
- Filter by topics and expressions
- Explore live traffic via Message Explorer
- Use AI agents to propose mapping definitions from observed/provided payloads
- Run in multi-tenant environments
| Connector | Purpose |
|---|---|
| AMQP 0-9-1 | Connect to brokers like RabbitMQ |
| AMQP 1.0 | Connect to AMQP 1.0 systems (Azure Service Bus, Artemis, Solace, etc.) |
| Apache Kafka | Integrate with Kafka topics |
| Apache Pulsar | Integrate with Pulsar topics |
| Cumulocity API | Create/update/delete managed objects, events, alarms, measurements |
| Cumulocity MQTT Service | Use Cumulocity's built-in MQTT broker with device isolation |
| Google Cloud Pub/Sub | Publish/subscribe data via a Google Cloud Pub/Sub topic and subscription, e.g. for ingestion into Google's Manufacturing Data Engine (MDE) |
| HTTP Connector | Receive payloads via REST endpoints |
| MQTT Broker | Connect to third-party MQTT brokers (HiveMQ, Mosquitto, etc.) |
| Webhook | Forward data to external REST APIs |
Everything beyond this page, CHANGES.md, and FAQ.md lives under docs/ — see
docs/README.md for the full index. Frequently needed pages:
- Architecture Overview
- Installation Guide
- User Guide — the full walkthrough of using the deployed app lives in the app itself (Help menu),
built from
dynamic-mapper-ui/public/docs - FAQ
- Limitations
- Extensions Guide
- Backend Docs
- Frontend Docs
- Smart Functions Docs
- Test Concept
- REST API docs: resources/openAPI/README.md
- OpenAPI spec: resources/openAPI/openapi.json
- Swagger UI (runtime):
{yourTenantURL}/service/dynamic-mapper-service/swagger-ui/index.html
Project modules and common commands are documented in AGENTS.md and module docs.
# Build all modules (from repo root)
mvn clean package
# Backend tests
cd dynamic-mapper-service
mvn test
# Frontend dev / tests
cd ../dynamic-mapper-ui
npm start
npm test- JMeter profile: resources/testing/performance/jmeter/jmeter_test_01.jmx
- MQTT JMeter extension: emqx/mqtt-jmeter
- Python MQTT load generators: resources/testing/performance/mqtt/
- See resources/testing/performance/README.md for how to run them.
Import and export mappings from the Inbound Mappings / Outbound Mappings table in the UI, individually or all at once — there is no longer a standalone import script. Ready-made sets to start from:
- resources/samples/mappings-INBOUND.json
- resources/samples/mappings-OUTBOUND.json
- Documented overview: resources/samples/SampleMappings_21.xlsx (also as PDF, inbound / outbound)
User-defined JavaScript is executed inside the backend JVM with sandbox restrictions. The GraalVM context is configured to minimize guest-code access to host resources.
The sandbox behavior has been validated with examples such as:
- Accessing
process.envfrom JavaScript (blocked) - Accessing host class
java.lang.SystemviaJava.type(...)(blocked)
Reference: GraalVM Sandboxing
These tools are provided as-is and without warranty or support. They do not constitute part of the product suite. Users are free to use, fork and modify them, subject to the license agreement. While we welcome contributions, we cannot guarantee to include every contribution in the main project.
For more information, see cumulocity.com or ask a question in the Cumulocity Community.