Zaptec Service bus subscriptions

Message Subscriptions

An installation can be configured with an AMQP (Azure Service Bus) message subscription.
Third parties can connect to subscriptions to receive continuous push notifications when a charging station’s state changes.

State observations include details such as charge mode, charge current, session energy, etc.
A list of observations provided to messaging subscriptions can be found in the integration document under State observation reference.

Message subscriptions must be activated in the user group. This has to be done through a Support request.
You can create a ticket via the help desk.

📘

Subscriptions are automatically removed after 14 days without use.

Enabling a subscription will configure an Azure Service Bus Topic for your user group.
Messages received from installed chargers will be broadcast to this topic.

There are multiple options for receiving messages from Azure Service Bus.

In addition to using Microsoft’s Service Bus libraries, messages can be consumed using the standard protocol AMQP 1.0, detailed here.

Credentials

Once a messaging subscription is enabled, connection details can be retrieved through:

• For production purposes:
  Connection details must be retrieved from this API method: API call (accessible by users with installation owner roles).

curl -X 'GET' \
  'https://api.zaptec.com/api/userGroups/<usergroupId>/messagingConnectionDetails' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer <bearer_token>'

📘

As connection credentials and host can change at any time, always query the API for updated connection details before connecting.

• For development or testing purposes:
  Connection details can be manually retrieved in the Zaptec Portal user group (accessible by owners of the user group).

Example: Message Subscription Connection Details

Connection details can be combined into a Service Bus connection string:

Endpoint=sb://{Host}/;SharedAccessKeyName={UserName};SharedAccessKey={Password};EntityPath={Topic}

Messages are published to a topic but can only be received from the topic subscription.

Depending on the library used to connect to the service bus topic, you may need to combine the topic and subscription name in your connection settings.
The full name of the topic subscription is:

{Topic}/subscriptions/{Subscription}

❗

• Observation Subscription Limit. Please be aware, observation messages from an installation can only be sent to a maximum of two service bus subscriptions simultaneously.

  This means if an installation has access enabled for more than two user groups, and all these groups have message subscriptions active, only two of the configured subscriptions will receive the observation messages. The system does not guarantee which two subscriptions will receive the messages if more than two are active.

• Message subscriptions will be disabled after 14 days without messages being sent (e.g., chargers offline) or without messages being consumed.

• Connection details will be reset when a subscription is disabled.

• Message TTL is 5 minutes. Any state observation not consumed within this period will be lost.

Message Format

Messages are provided as JSON-serialized ChargerState objects:
https://api.zaptec.com/help/index#!/Charger/Charger_ChargerState

Each message contains:

• ChargerId
  The UUID of the charger providing the message.

• StateId
  The ID of the changed state observation. A list of supported state observation IDs can be found in the State observation chapter.

• Timestamp
  The UTC timestamp when the state observation was changed, provided as an ISO 8601 string.

• ValueAsString
  The new state value, serialized as a string.

  Boolean: true = 1, false = 0