Skip to main content

MQTT Integration (UBC.mqtt)

UBC - Unified Backend Connector includes a component for acting as an MQTT client (over WebSocket), available from version 750 onwards. It enables real-time, fail-safe messaging without requiring middleware management or handling topics related to system availability, buffering, or firewalls.

Unlike SAP's standard implementation, UBC.mqtt supports persistent sessions, unlocking entirely new capabilities for your SAP system without the need for middleware technology.

This document describes the technology and how to integrate a new use case.

Key Advantages of Using UBC.mqtt​

  • No firewall issues—connection is established "from" the SAP system via MQTT over WebSocket "inside out."
  • "Clean session" configuration enables persistent sessions, allowing the MQTT broker to store messages when disconnected.
  • Available from version 750 onwards.
  • The only required component is an MQTT broker, which distributes messages to clients.

Overview from an SAP Perspective​

MQTT Client​

There are two main ways to set up UBC as an MQTT client. Regardless of the method, both unlock all MQTT capabilities for direct SAP connection:

  • Running the client in a periodically scheduled job:

    • If the job runs every minute, the SAP-UBC client connects to the broker, waits for messages for a predefined duration, and then disconnects.
    • A "clean session" is not suitable for this scenario; it must always be persistent (QoS >= 1).
    • Template: /UBC/S17_MQTT_WS_CLIENT

  • Running the client as an ABAP Daemon:

    • An MQTT daemon runs continuously per client, keeping the WebSocket connection to the broker active.
    • New messages are pushed immediately to the SAP system/MQTT client.
    • The daemon, a subclass of /UBC/CL_MQTT_DAEMON_ABS, is scheduled independently.
    • Availability: Daemons are supported in S/4HANA but not in ECC (use the job method instead).
    • If a persistent session (QoS >= 1) is configured, messages will be received after reconnection.
    • Example: /UBC/CL_S17_MQTT_DAEMON for the S1Seven use case.

Recommendation​

Use daemons if available. However, since daemons cannot guarantee 24/7 availability (due to downtimes, etc.), configuring a "persistent session" is recommended. Typically, only one daemon per system is needed (not per client/application server), controlled by the server group (RZ12).

info

For acting as a client (subscription/pull), handlers can be linked to topics. For publishing messages, only daemons provide out-of-the-box functionality: /UBC/IF_MQTT_CONTROL_CLNT_ASY~PUBLISH.

Handler​

Each "proxy" (endpoint) automatically registers for all topics specified in /UBC/CUSTOMIZING under the MQTT handler configuration section for its proxy type:

MQTT handler configuration

A topic is linked to its implementation, and the QoS (Quality of Service) is specified. Using "at least once" ensures message delivery in SAP (persistent session).

Once a message is received, it is transmitted to the bgRFC destination /UBC/INBOUND (automatically created during system setup for UBC; see transaction SBGRFCCONF).

This mechanism utilizes parallel processing based on scheduler and server group configurations. The bgRFC executes the handler class specified earlier. Depending on the QoS setting, messages are acknowledged after transmission to the bgRFC runtime. For technical errors, refer to SAP monitoring transaction SBGRFCMON.

Handler Implementation​

Generic superclass options for handler implementation:

  • /UBC/CL_MQTT_HDL_REC_JSON_ABS – For JSON payloads (default format: lowercase). Override DESERIALIZE_MESSAGE if a different format is needed.
  • /UBC/CL_MQTT_HDL_REC_STRING_A – For STRING payloads.
  • /UBC/CL_MQTT_HDL_REC_ABS – For other formats (requires implementing DESERIALIZE_MESSAGE in ABAP).

Example for STRING:

class zubc_cl_mqtt_msg_string definition
  public
  create public
  inheriting from /ubc/cl_mqtt_hdl_rec_string_a.

  public section.
  protected section.
    methods on_message redefinition.
  private section.
endclass.

class zubc_cl_mqtt_msg_string implementation.
  method on_message.
    data(lr_message) = ref string( iv_message ).

    "TODO: Process string
  endmethod.
endclass.

The class ZUBC_CL_MQTT_MSG_STRING is specified in customizing for a topic.

Simple Implementation​

UBC provides an out-of-the-box implementation for basic use cases where the endpoint only connects to an MQTT broker.

Setup​

Run transaction /UBC/MQTT_SMPL_SETUP. This must be configured on each system, as it is not transportable.

  • Configure Proxy
    Configure Proxy details

    • Organization ID: Unique identifier for the use case.
    • MQTT over WebSocket endpoint: Fully qualified domain name (FQDN) pointing to the broker.
    • Username and password: Stored securely and used for authentication.

  • MQTT Daemon Setup (Daemon or Job)

    tip

    Daemons are recommended.

    • RFC Destination: Used for daemon login. See here for details.
    • Server Group: Recommended to assign to one application server only.

  • Schedule MQTT Job for Asynchronous Events If a daemon is unavailable, schedule a job for report /UBC/MQTT_SIMPLE_WS_CLIENT in SM36.

Handler Implementation (Inbound)​

See Handler. Specify topics for proxy type MB (MQTT Broker, Simple).

Publish Message (Outbound)​

info

Supported only for daemons, which must be running.

Example:

/ubc/cl_daemon_mqtt_simple=>factory( )->publish(
  is_proxy_key = value #( organization_id = 'YourBrokerOrgId' )
  io_packet    = /ubc/cl_mqtt_packet_publish=>factory(
                     )->set_qos_level( /ubc/if_mqtt_packet=>mc_qos-at_least_once
                     )->set_message( value #( topic = /ubc/cl_mqtt_topic=>factory( 'SAP/1' )
                                              message = cl_binary_convert=>string_to_xstring_utf8( 'test' ) ) ) ).

Custom Implementation​

For proxies that require brokers behind them, implement a custom proxy class inheriting from /UBC/CL_PROXY and override CREATE_MQTT_CLIENT_CONFIG to return /UBC/IF_MQTT_CLIENT_CONFIG.

Example: /UBC/CL_S17_PROXY