Utility Cloud Connector

An eMabler Connect integration for energy companies billing EV charging in Utility Cloud.

1. Overview

The Utility Cloud Connector is a bi-directional, event-driven integration between eMabler Connect and Utility Cloud, a billing, contract management, and CRM platform widely used by energy companies in the Nordics.

The connector lets an operator run their EV charging service end-to-end inside their existing Utility Cloud tenant. Customer, contract, and accounting point data stay in Utility Cloud. Chargers, drivers, sites, RFID tokens, and sessions stay in eMabler. The two systems keep each other in sync automatically.

2. Who uses it

The connector is built for energy companies and utilities that already use Utility Cloud as their core billing and contract platform and want to offer EV charging as a natural extension of their electricity product, without rebuilding their billing stack or running EV charging on a separate silo.

Typical buyer profile:

• Energy retailers offering a charging subscription (for example, Ladeabonnement) on top of an electricity contract.

• Operators who want the Utility Cloud customer app to be the driver-facing experience.

• Companies whose customer service and finance teams already work inside Utility Cloud and do not want to switch tools.

• Operators planning to use Utility Cloud Revenue Share to split charging income with site owners (for example, housing owner associations or property owners).

2.1 Customer types and integration modes

The connector supports two customer integration types. The table below shows each type and its current status. The two modes are explained in section 3.3.

3. How it works

The connector is event-driven over a shared Azure Service Bus topic. Utility Cloud pushes contract lifecycle events to eMabler. eMabler pushes charging data back to Utility Cloud over HTTPS, authenticated with OAuth2 client credentials issued by Microsoft Entra.

Two modes for the outbound charging data are supported: the meter-value mode (Type A, legacy) and the costed-transaction mode (Type B, current and default for new customers). Section 3.3 compares them. Contract event handling is identical in both modes.

3.1 Architecture and tenant routing

All Utility Cloud tenants publish contract events to a single Azure Service Bus topic owned by eMabler. eMabler subscribes to that topic and accepts only events where Header.ServiceType equals ChargingAgreement; everything else (other service types, unrelated event names) is ignored. The GLN (Global Location Number) carried in Header.TenantID identifies which Utility Cloud tenant the event belongs to and is mapped one-to-one to an eMabler customer.

Topics in use:

• Production: utilitycloudcontracteventsprod on sb://emablerintegrationservicebusproduction.servicebus.windows.net

• Staging: utilitycloudcontracteventstest on sb://emablerintegrationservicebustest.servicebus.windows.net

3.2 Mastership split

3.3 Two integration modes

The connector supports two modes for sending charging data to Utility Cloud. The choice is per customer and is set during onboarding. Existing Type A customers keep running on meter-value mode until they migrate; new customers go straight to costed-transaction mode.

3.4 Driver onboarding flow

Onboarding starts the moment Utility Cloud activates a contract for a charging subscription. Within seconds, an eMabler driver exists and can charge on the operator network. This flow is identical in both integration modes.

Key fields read from the ContractActivated event:

• Header.TenantID: GLN, mapped to eMabler customer.

• Header.ServiceType: must be ChargingAgreement. Events with any other service type are ignored.

• Payload.Contract.AccountingPoint.Identification: becomes the driver externalId, and the transactionOwnerId on outbound costed transactions.

• Payload.Contract.AccountingPoint.Details.Rfid: optional pre-set token, otherwise eMabler generates one with the v: prefix.

• Payload.Contract.AccountingPoint.Details.PrivateSiteId: optional pre-set site assignment in Connect (integer, validated at parse time).

3.5 Charging session, costed-transaction mode (Type B, current)

In costed-transaction mode, eMabler runs the full session, applies the operator tariff, calculates total cost with VAT and currency, and posts a single transaction object to the Utility Cloud InvoiceLineImport endpoint. Utility Cloud imports the result as an invoice line. If the site is set up for Revenue Share, eMabler also resolves and attaches a revenueShareId so Utility Cloud can split the revenue.

Payload fields on POST /se/invoicelineimport/v1/transaction:

• transactionId: eMabler session ID, used by UC as the natural key and by GET requests.

• transactionOwnerId: on eMabler this is the driver externalId, on UC this is the Accounting Point identifier of the Charging Agreement contract.

• siteId: numeric eMabler site identifier. Always sent on the payload; falls back to -1 when no site has been resolved for the driver.

• authorizedTag and authorizedTagName: RFID or virtual token used to start the session, with the human-readable label.

• timestampStart and timestampEnd: session start and stop in ISO 8601 UTC.

• fullConsumptionKWh: total kWh delivered in the session.

• currency, vatPercent, totalCostInclVat, totalCostExclVat, totalVat: eMabler-computed pricing, ready for direct import to UC billing.

• creditReferenceTransactionId: optional, identifies the original transaction when this record is a credit or correction.

• revenueShareId: optional. Identifies a Revenue Share contract on the UC side. When set, UC redistributes income according to that contract. See section 3.7.

3.6 Charging session, meter-value mode (Type A, legacy)

Meter-value mode is the original integration, used by Type A customers. eMabler runs the session as normal but does not price it. Instead, eMabler sends raw meter values (a kWh series with start and end timestamps) to the Utility Cloud meter-value adapter. Utility Cloud applies its own tariff catalogue to compute cost and produces the invoice line.

Notes:

• Endpoint: POST https://api.utilitycloud.app/v1/se/general-mv-adapter/CreateMeterValuesSeries.

• Key identifier on payload: AccountingPointIdentifier, same value as the costed-transaction transactionOwnerId.

• No siteId, no revenueShareId, no pricing fields. Currency and VAT are owned by Utility Cloud.

• No support for Revenue Share. An operator that needs Revenue Share must migrate to costed-transaction mode.

3.7 Revenue Share tagging

Utility Cloud Revenue Share is a UC product that lets the operator share charging income with a third party such as a housing owner association, a property owner, or an employer. The split is configured as a Revenue Share contract on the UC side and identified by a single numeric ID.

eMabler enables Revenue Share by attaching revenueShareId to every outbound costed transaction that originates at a revenue-shared site. The mapping from eMabler site to revenueShareId is held in Connect and resolved at the moment the transaction is priced.

How it works end to end:

1. Operator creates a Revenue Share contract in Utility Cloud and obtains a revenueShareId.

2. Operator configures the eMabler site to point at that revenueShareId.

3. A driver charges at a charger on that site. eMabler runs the session and prices it.

4. Before sending the transaction to UC, eMabler looks up the site, finds the revenueShareId, and attaches it to the transaction payload.

5. Utility Cloud imports the transaction as an invoice line and applies the Revenue Share contract, splitting the revenue between the operator and the third party.

Field naming note: an earlier draft used MeteringPointId for this field. It was renamed to revenueShareId in November 2025 and that is the only name used today. AccountingPointId on the same payload was renamed to transactionOwnerId at the same time.

3.8 Contract lifecycle and driver access

Utility Cloud emits three event names that eMabler listens for. Each one updates the corresponding driver in Connect. This is identical in both integration modes.

• ContractActivated: eMabler creates the driver, attaches a virtual token, assigns the site. Driver can charge immediately.

• ContractUpdated: eMabler re-evaluates access for the driver and applies changes to RFID, SiteId, or product attributes.

• ContractTerminated: eMabler revokes access and deactivates the virtual token. Any in-flight session is still settled and reported.

All other UC event names (for example, TPContractCreated) are filtered out at the Service Bus subscription. eMabler does not need to handle them.

3.9 Failure handling

• Service Bus DLQ: messages that fail eMabler parsing (for example, malformed PrivateSiteId) move to the dead-letter queue and are picked up by support.

• OAuth errors: a 401 from Microsoft Entra blocks transaction delivery for that tenant. Transactions are retried until the operator credential is fixed.

• UC API errors: a 4xx from the InvoiceLineImport or meter-value API is logged on the Logs tab in Connect (see section 5).

• Missing revenueShareId on a revenue-shared site: the transaction is still delivered without the revenueShareId tag and is logged for manual reconciliation. UC treats it as a normal invoice line until corrected.

4. What is included

The Utility Cloud Connector includes the following capabilities out of the box.

5. Setting it up in Connect

The connector is configured under the Integrations section in eMabler Connect. Once activated for an organisation, the integration page exposes three tabs.

Details

Connection status, tenant identifier (GLN), and the API key used by Utility Cloud to call eMabler.

Advanced settings

Site or group mapping for newly created drivers, virtual RFID prefix, Accounting Point ID validation rules, and the Service Bus topic used for incoming events.

Logs

Searchable, time-filtered log of every request between Utility Cloud and eMabler. Each entry shows endpoint, action, response code, reference ID, and the full request payload for troubleshooting and audit.

5.1 Prerequisites and handover

To activate the connector for a new operator, the following needs to be in place. The integration team runs this checklist with the customer during onboarding.

• Operator creates an app registration in their Azure AD for eMabler to use and shares the client_id and client_secret with eMabler.

• Operator shares the same client_id with Utility Cloud so UC can recognise eMabler in their tenant.

• eMabler shares the Service Bus connection string (topic) with Utility Cloud for event forwarding.

• Utility Cloud enables ServiceType ChargingAgreement on the operator tenant and forwards ContractActivated, ContractUpdated, and ContractTerminated events for that service type to the agreed Service Bus topic.

• Utility Cloud confirms the tenant GLN, which eMabler maps to the operator customer in Connect.

• Tailored service types are transferred from the staging tenant to the production tenant on the Utility Cloud side.

Day-to-day configuration changes after activation (site mappings, RFID prefix, log inspection) are self-service from the Integrations page.

6. Related documentation

• eMabler API v2 reference: https://docs.emabler.com/docs/api-v2-documentation

• Integrations and OCPI guide: https://docs.emabler.com/docs/integrations

• Utility Cloud InvoiceLineImport API (current): api.utilitycloud.app/se/invoicelineimport/v1/transaction

• Utility Cloud meter-value API (legacy): api.utilitycloud.app/v1/se/general-mv-adapter

• Utility Cloud Revenue Share product: available from Utility Cloud (contact support@utilitycloud.no).