Documentation

Appearance

How do we integrate Dataplicity with ERP, CRM, billing, and external APIs? #

Do not copy your whole ERP, CRM, billing, or domain backend into Dataplicity. Define which system owns each fact, exchange only the data required by the connected product, and make reconciliation explicit.

Dataplicity should usually own connected-product state and operations. Your business systems should continue owning their existing domains.

Start with authority, not API mechanics #

Before building an integration, write down the system of record for each important fact.

For example:

FactAuthoritative system
Customer legal accountERP/CRM
Invoice/payment statusBilling/accounting
Product modelOEM product master / Device Class
Device cloud identityDataplicity
Current device connection/product stateDevice + Dataplicity
Customer/site allocationDefine one owner; synchronise deliberately
Financial transaction ledgerDomain backend/accounting system
Product workflow stateProduct Application if appropriate

If two systems both believe they are authoritative, eventual disagreement is not an integration bug; it is an architecture bug.

Integrate around business events #

Useful integration triggers include:

  • order fulfilled -> allocate device to customer;
  • device commissioned -> update asset/service record;
  • customer/site created -> create or map connected-product tenant;
  • device alarm -> create external service ticket;
  • service entitlement changes -> update permitted workflow/state;
  • Product Application process completes -> notify domain backend;
  • device retired -> update external asset lifecycle.

Keep payloads narrow and idempotent.

Use stable external identifiers #

Map entities using stable IDs rather than names.

For example:

text
ERP customer id: CUST-18421
Dataplicity customer id: ...

Store the mapping in a deliberate integration layer or supported metadata field where appropriate.

Names, email addresses, and site labels can change. They are poor primary keys for synchronisation.

Make writes idempotent #

An integration can retry because of timeouts, network failures, or queue replay. Repeating the same request should not create duplicate customers, allocations, invoices, or transactions.

Use stable operation/event identifiers where the business effect matters.

For example:

json
{
  "event_id": "erp-device-allocation-883102",
  "customer_ref": "CUST-18421",
  "device_serial": "GW-009918"
}

The receiving side should recognise a replay where practical.

Do not couple physical safety to ERP availability #

If the ERP is down, your physical product should not suddenly become unsafe.

Use external business systems for policy, commercial state, and workflow where appropriate. Keep local safety and essential offline behaviour on the device.

For time-sensitive entitlement, credit, or access systems, design an explicit offline model rather than making each physical operation synchronously dependent on an ERP API.

See Offline datasets.

Decide between synchronous API calls and asynchronous events #

Use synchronous calls when the user genuinely needs an immediate response from the other system and failure can be handled clearly.

Use asynchronous integration when:

  • either system can be temporarily unavailable;
  • retries are expected;
  • the workflow should continue independently;
  • throughput varies;
  • reconciliation matters more than immediate coupling.

A queued integration process with explicit status is often easier to operate than a long chain of synchronous calls across device, Dataplicity, ERP, payment provider, and CRM.

Avoid hidden circular updates #

Bidirectional sync is dangerous when both sides automatically rewrite each other.

If customer names sync from CRM to Dataplicity, do not also push every Dataplicity display-name edit back into CRM unless that authority rule is intentional.

For each field define:

  • owner;
  • allowed direction;
  • update trigger;
  • conflict policy;
  • audit expectations.

Use Product Applications where they reduce glue code #

A Product Application can own bounded connected-product workflow state and integrate outward at the boundary.

That can be cleaner than building a custom backend merely to coordinate a small number of device/customer records and actions.

But if your integration logic becomes a broad enterprise integration platform, use tooling designed for that problem.

Configure the Product Application workflow #

Use the Application Workspace when the connected-product domain fits the authority model above:

  1. In Build, define the Product Record models and stable external-ID fields that the integration needs. Keep financial ledgers and broad enterprise data in their authoritative systems.
  2. In Behaviour, expose only the Operations needed by the business workflow and call outbound bindings from bounded Rules, Operations, or Processes.
  3. In Access, use Add integration for outbound HTTPS bindings and Create API client for each customer system. Select the Product Instance and grant only its required record or Operation scopes.
  4. In Release, publish the immutable application version and attach it to the customer portal. Each attachment creates an isolated Product Instance; do not reuse its client secret for another customer.
  5. For inbound business events, provision an endpoint on that Product Instance with an explicit event and Operation allowlist. Give the sender the endpoint secret, require a stable idempotency key, and use HMAC-SHA256 when the sender supports request signing.

Follow Connect the Product API and integrations for the end-to-end task. The implementation references cover authentication and scoping, Product Records, Product Query, reporting and CSV export, and inbound and outbound delivery.

Operate durable outbound work from its delivery state rather than treating submission as completion. Retryable failures enter retry_wait; exhausted retryable deliveries enter dead_letter. Review the recorded attempts, correct the destination or credential, and replay deliberately. Preserve the same business idempotency identity at the receiving system because replay does not make a third-party side effect exactly once.

Operationalise the integration #

Production integration needs more than a successful API call in development.

Monitor:

  • authentication expiry/failure;
  • rate limits;
  • queue backlog;
  • repeated retries;
  • dead-letter/failure state;
  • mapping failures;
  • schema/version changes;
  • reconciliation discrepancies.

Provide a way to replay or repair failed business events without manually editing databases.

Security boundary #

Use the narrowest credentials and permissions required. Do not embed ERP or cloud master credentials on field devices.

A device should normally communicate through the device/product contract. Backend-to-backend integrations can use the appropriate Dataplicity API credentials and external-system credentials from a secure server environment.

See API keys, the Gateway API, and the Product Application API.