Disclaimer

©2024 Deutsche Boerse AG - All rights reserved. The information contained in this document is confidential or protected by law. Any unauthorized copying of this document or part of it or unauthorized distribution of the information contained herein is prohibited. All materials provided by DB in this context are and remain the intellectual property of DB and all rights therein are reserved.

Terminology

1 Introduction

This document describes the Public Message Interface that the backend system provides to its third party clients.

The Public Message Interface allows clients to communicate with the backend system via a programmable interface.

There are two kinds of communication between clients and the backend:

• Management and inquiry requests initiated by the client applications, and the corresponding replies from the backend
• Broadcast messages sent by the backend to all or specific clients, triggered by market events (e.g. new orders or trades) or by changes in public or private reference data

The communication with the backend system is based on the Advanced Message Queuing Protocol (AMQP) as the transport layer. AMQP is a platform- and language-neutral open standard for the wire protocol¹ on the application layer of the OSI model.

Payload of the messages sent over AMQP is formatted in XML. See www.w3.org/XML for information about XML.

For the Administrative Message Interface that the backend system provides to client applications that supports users with administrative privileges such as Market Operation, please refer to the DFS180a.

1.1 Overview

Clients that use the Message Interface communicate with an AMQP server, which in turn communicates with the backend system. The backend system itself is behind a firewall and is not directly accessible to the clients.

Overview of the communication between clients and the backend system

The AMQP server is currently using the AMQP implementation from RabbitMQ. This version supports AMQP versions 0.9.1, 0.9 and 0.8. See www.amqp.org and www.rabbitmq.com for more information.

For an optimal interoperability, clients should be implemented using the latest AMQP client library for RabbitMQ, as interoperability limitations are known in the RabbitMQ server implementation. Please refer to the following webpage: https://www.rabbitmq.com/interoperability.html.

1.2 Public Message Interface Terms of Service

Thank you for using the M7 Trading Public Message Interface. By accessing and using this API, you agree to the terms of service described below. Additional terms of use may apply per the relevant market authority. We refer to the terms listed below and throughout this document, as well as terms within the accompanying API documentation, and any applicable policies and guidelines as the “Terms.” You agree to comply with the terms and that your usage and ability to access these services is based upon your compliance to these terms. Please read this documentation and all Terms carefully. Deutsche Börse AG reserves the right to revoke access to the M7 Trading Public Message Interface (API) and any other services if connected clients are not compliant with the Terms described in this documentation.

1.2.1 Usage of the M7 Trading Public Message Interface

1.2.1.1 Permitted Access

You will only access (or attempt to access) an API by the means described in the documentation of that API. You will use the application ID and user credentials assigned to you by the issuing authority only. Where required, SSL/TLS Client Certificates may only be used by the party they have been explicitly issued to. Redistribution of SSL/TLS certificates is not permitted.

1.2.1.2 Managed End Users

All end users of the connected client will comply with the terms described here, the terms of the applicable market authority, as well as all applicable local laws and regulations.

1.2.1.3 Compliance with Law, Third Party Rights, and Market Authorities

You agree to comply with all applicable laws and regulations, as well as third party rights (including without limitation laws regarding the import or export of data or software, privacy, and local laws). You will not use the API to encourage or promote illegal activity or violation of third-party rights. You will not violate any other terms of service with Deutsche Börse (or its affiliates).

1.2.1.4 Public Message Interface Limitations

Deutsche Börse sets limits on the use of its APIs (e.g. limits towards the volume and frequency of all or some requests that you may submit), per its discretion. You will comply with the documented limits and will not make attempt to circumvent them. Further guidelines are recommended in this documentation per suggested implementation against our API. Deutsche Börse reserves the right to revoke or suspend access to clients exhibiting API usage behavior contrary to the terms, guidelines, and suggested implementation practices described in this and related documentation. For the sake of clarity, access to the API may be suspended or revoke for behavior including but not limited to the following:

• Users producing unnecessarily large volumes of entities on the message broker (e.g. AMQP ‘queues’, ‘channels’, ‘connections’ or ‘consumers’)
• Clients found unable to acknowledge or consume their messages from the message broker in an appropriate time (see section Flow Control)
• Clients not implementing exponential back-off approach for repeated re-connection attempts, or
• Clients sending messages way above the limits.

Please refer to the documentation here, and the linked third party documentation for the suggested implementation of these concepts.

2 Getting Started

To get started with the Public Message Interface, you need to:

• Request an account for the AMQP server at the granting authority. You will obtain the following package:
  • A TLS client certificate and password to connect to the AMQP Server (see section Security)
  • A unique application id that has to be used for further communications with the backend system
  • The message format of the XML Schema files. You will need the schema files to be able to correctly format messages sent to the backend system and to read its responses. See section 5 for further details.
• Request a trader account if one does not already exist, for participating in the market.
• Download the AMQP client library for RabbitMQ from www.rabbitmq.com. Libraries from other AMQP vendors are not supported due to interoperability issues (vendor interoperability is expected to be implemented from AMQP version 1.0).
• Implement your client. The way that your program should communicate with the backend system is described in the section Message Exchange Patterns.

2.1 AMQP

AMQP (Advanced Message Queuing Protocol) is a wire-level protocol that enables message-based communication through the use of an AMQP compliant middleware server (the message broker). In the case of the Public Message Interface this message broker is RabbitMQ.

AMQP defines a modular set of components for the broker as well as standard rules for connecting them. There are 3 main types of components, which are connected into processing chains to create the desired functionality:

• The “exchange” receives messages from publisher applications and routes these to “message queues” based on arbitrary criteria, usually message properties or content
• The “message queue” stores messages until they can be safely processed by a “consuming” application (or multiple applications)
• The “binding” defines the relationship between a message queue and an exchange and provides the message routing criteria

The exchanges, message queues and bindings that are set up by the backend system are described in more detail in the following chapter.

Please refer to the AMQP and RabbitMQ documentation for more details on the use and configuration capabilities of both AMQP and the RabbitMQ client library.

2.1.1 Connecting to the AMQP server

The first step every client program needs to take is to establish a connection to the AMQP server. This connection can then be used to create the channels that are used to communicate between the client application and the backend server. The various channels needed to communicate with the backend can all share the same connection. The same holds true for a multithreaded implementation: all threads of a client program typically share the same connection, but channels cannot be shared; each channel can only be used by a single thread.

Creating a connection requires the following information to be specified:

• Username, password, server host, port and the virtual host to connect to. This information will be supplied by the granting authority.
• TLS context: client certificate and client certificate key

It is mandatory that all connections to the AMQP server are created with AMQP heartbeats enabled. The recommended heartbeat period is 30-60 seconds. Connections that do not have heartbeats enabled will time out on the firewall in the event that there is no traffic on the connection for a longer period of time.

In addition, client programs may want to register a shutdown listener on the connection and/or on channels. This can help the application to detect a connection loss faster.

2.1.2 Client Failover

Access to the AMQP server is possible through two different data centres with different IP addresses and URLs. In the standard operating phase, both data centres are active and can be used to make a connection.

All connection details (the port, username, password, client certificate) are the same for each data centre apart from the URL or IP address.

Failover support needs to be implemented on the client side by using the URLs provided. In case a connection through the first URL is not possible, the client shall try to connect to the second URL. DBAG generally suggests to implement a round-robin solution within the log-in procedure to minimise the operational impact in case one data centre is temporarily unavailable.

Please notice that independent of the URL / IP address that is chosen to connect to, all commands will always be routed to the master backend instance

2.2 Application ID

Each client application will receive its own id that has to be used to enable further communication with the backend system. If no application id is used, or the application id is not configured in the backend system, the client will not be able to participate in the market. The application id will be verified by the backend system for each request.

The application id will be given to each client by the granting authority. Each client is responsible to keep its id secret.

3 Message Exchange Patterns

Two basic patterns of message exchange are supported between the client and the backend system:

• Request-response communication, where a client issues a request and waits for a response from the backend system. Each response message is addressed to a specific client (the one that issued the request). This type of communication is initiated by the client.
• Broadcast communication, where the backend system publishes notifications that are either public - addressed to all traders - or private - only receivable by privileged traders. Clients may subscribe to receive notification broadcasts that they are interested in. This type of communication is initiated by the backend system.

Typically, all market related information is broadcast by the backend system to all of the client applications that are authorised to receive that information.

The request – response communication is mainly reserved for “actionable” requests (called “management requests” in the rest of the document) e.g. order entry, trade recall request, etc.

The “inquiry requests” serve to obtain information on the current state of the market or reference data. However, they should only be used at the start of a new session to obtain an initial view of the market, or when recovering from communication failures. Subsequent changes in the market situation will be broadcast by the backend system to all connected client applications which should handle these broadcasts, to update the market and reference data they present to their users accordingly. Failing to comply with that pattern may lead to revocation of the respective application id. Note that the backend system limits the number of inquiry requests a client application may submit in a period of time to avoid the excessive and performance degrading use of inquiry requests.

The rest of this chapter provides more detail on these two modes of communication with the backend system.

3.1 Request-Response Communication

Traders that want to participate in the market send their requests to the backend system. Requests are sent to private trader-specific request exchanges. After processing a request, the backend system sends the response to a private response queue that belongs to the trader that has sent the request.

3.1.1 AMQP Configuration

In case a new trader has been set up by the granting authority, the backend system will synchronise with the AMQP Server during runtime and create the necessary exchanges and bindings.

The following diagram details the exchanges and queues that are set up in the AMQP server for request-response based communication between a typical client application and the backend system.

Request-response communication between clients and the backend system

A durable direct exchange named m7.requestExchange.<login-id> is set up on the AMQP server for each trader (indicated as “private request exchange X” in the figure above). These exchanges are used for trader requests of all request types.

The response queues used by the client for receiving responses upon requests will not be set up initially by the AMQP Server but by each client. Therefore, the client creates one private response queue and uses the queue name within the reply-to field of a request message.

The M7 system guarantees that it will process request messages from a client in the order in which the messages have been delivered to the queue on the AMQP server.

First of all, each client has to send a login request using a valid trader that is configured in the M7 system. Without it, a trader cannot participate in the market. As a result of a login request, a “User response” is sent containing all information required to participate in the market. The login of a client is checked by the M7 system.

The M7 system supports a single login functionality so that a trader can only be logged in once. As a result of this, the M7 system may send a “LogoutRprt” broadcast message containing the session id passed to the client within the “User response” after the login. This broadcast is sent whenever a trader is accessing the M7 system via a different interface or the Public Message Interface itself. When receiving a “LogoutRprt”, the trader is already logged out from M7. The client must perform a logout of its trader from Rabbit MQ. If the client does not perform a logout of the current trader and allows a parallel login of the same trader, both will consume messages from the trader’s response queue and therefore remove messages.

After receiving a “LogoutRprt” a trader can re-login, forcing the trader with the same login credentials to be logged out.

3.1.2 Request Types

The M7 Trading system supports two types of requests:

• Management-related Requests are used to enter, modify or delete orders or trades in the backend system.
• Inquiry Requests provide market or reference data which is accessible to the client.

As a response to a management request, M7 will send an “AckResp” message to acknowledge the receipt of this request by PIM Gateway for the further processing, or an “ErrResp” message to inform about possible errors. After processing the request, the backend system will send one or more broadcast messages containing the requested change. All of these responses are sent to the private response queue of the requesting trader.

If the request results in a change in the market or reference data, a second set of broadcast messages will be sent to all market participants (client applications) notifying them of the change.

Example

When a client application sends a new order to the M7 Trading RabbitMQ, it will receive an AckResp in reply to confirm the receipt of the order by PMI Gateway. After processing the request, the backend system will send an Order Execution Report to the client application and a Public Order Books Delta Report to all of the client applications that have access to the market data for the product concerned.

For details on the content of the requests, see section Message Format.

3.1.2.1 Management-related Requests

For management requests, it is possible to send multiple requests of the same type in a single message. The M7 Trading system confirms the receipt of the request with an AckResp message. Each individual request will be responded by an individual response message. If the system detects an error which prevents it from processing of the message (syntactical errors but also if the message content is against the M7 Trading documentation, for example if a buy ICB order has a positive peak price delta), it may reply directly with an ErrResp instead, sending it to the private response queue of the client.

When sending an order management request, the request may specify a client order id. The response sent by the M7 Trading system contains this client order id, to enable the client to identify the response to the order in its own system.

The maximum number of management-related requests that can be bundled in one single request is determined by a limit defined in the XML Schema files for each request. Should this limit be exceeded, the whole request message will be rejected and the client will get an error response containing information about the current limit setting. The limit may be subject to change in future schema versions.

3.1.2.2 Inquiry Requests

The following inquiry request types are supported:

• Private Message Requests are used to retrieve the client specific private information held by the backend system.
• Public Message Requests are used to retrieve public information held by the backend system.
• Trade Requests are used to retrieve all trades for products that a client is assigned to.
• Order Book Requests are used to retrieve the current order book situation managed by the backend system.
• Order Requests are used to retrieve orders based on the client assignments.
• Reference Data Requests are used to retrieve reference data needed by the client for initialisation.
• Throttling Status Requests (if available for the exchange) are used to retrieve the current Throttling status of the member.

For inquiry requests, it is only possible to send a single request in each message. The backend system returns a single response for each inquiry request.

3.1.3 How to Send Requests

In order to send a request to the M7 Trading backend system, the client shall perform the steps described in the following subchapters.

3.1.3.1 Response Queue Declaration

First of all, the client must declare at least one private exclusive response queue. This queue will be used during the entire time when the client is connected to the broker.

The maximum number of queues which a client can declare is 10. All declared queues must adhere to the following name pattern on the AMQP server:

• m7.private.responseQueue.<login-id>.queue1
• m7.private.responseQueue.<login-id>.queue2
• m7.private.responseQueue.<login-id>.queue3
• m7.private.responseQueue.<login-id>.queue4
• m7.private.responseQueue.<login-id>.queue5
• m7.private.responseQueue.<login-id>.queue6
• m7.private.responseQueue.<login-id>.queue7
• m7.private.responseQueue.<login-id>.queue8
• m7.private.responseQueue.<login-id>.queue9
• m7.private.responseQueue.<login-id>.queue10

3.1.3.2 Request Preparation

Once the queue(s) have been declared, the client may proceed with the preparation of an AMQP request message.

A request is an XML-encoded message embedded in the message body. The detailed payload description of each public request can be found in Public Requests and Responses. For privileged requests mainly designated for Market Operators and Admins, please refer to DFS180a.

Each request must be built in line with the currently valid set of M7 Trading XSDs as well as with the business logic of the M7 Trading application.

In addition to the correct XML format, the client will also be required to set the message attributes in the AMQP message header as per AMQP Message Properties.

3.1.3.3 Event-index Inclusion

As of M7 6.16, it is recommended to include the latest value of the optional message property event-index in all inquiry requests sent to M7. For more information, please refer to Event-Index.

3.1.3.4 Sending Request

The client shall send the XML-encoded request from Request Preparation to the m7.requestExchange.<login-id> exchange. The routing key to be used depends on the type of the request:

• m7.request.management routing key for management requests
• m7.request.inquiry routing key for inquiry requests
• m7.request.inquiry.throttling for the current throttling status of the Member

The first request that the M7 Trading application will expect to receive is a LoginReq (see LoginReq).

3.1.3.5 Obtaining Response

Once the backend system has processed the request, it will send a response to the client’s response queue specified in the reply-to attribute from the request. The response message is sent with the correlation-id attribute set to the value contained in the request. This allows the client to match responses with requests. If the processing fails (e.g. an unexpected disconnection from XBID occurs before the OrdrExeRprt could have been received from XBID, and the open expectation in system memory expires), the correlation-id might be lost, because its value is stored only in the open expectation. It is also possible to use clientCorrelationId attribute for request-response matching purposes.

The backend system will send a response to each request. As long as the XML schema version used by the client is supported by the backend system, the response will be encoded using the same schema version that was used for the request.

The response and broadcast messages sent by the M7 system carry the timestamp message property attribute, containing the time message had been sent.

For details about the request and response formats, see Message Format.

3.1.3.6 Invalid and Unrouteable Requests

If the backend system cannot process a request, because the request is incorrect or cannot be fulfilled, it will send a negative response. The response message contains details about why the request could not be processed.

If the backend system cannot process the request because the XML schema version in the request message header is missing or invalid, the backend system will send a native error response. This response has the content-type attribute set with a value of x-m7/error. The body contains an error message encoded in UTF-8. The reasons for sending a native error message may be caused by validation errors detected by the backend system. Validation errors may occur when some mandatory AMQP message header attributes were omitted in the request (see Sending Request).

The error response is sent to m7.private.responseQueue.<login-id>.queue<1-10> queue set inreply-to attribute. If reply-to is not set, error is sent to m7.broadcastQueue.<login-id> queue.

If the backend system cannot process the request because its XML code is invalid, it will send a special xml error response. See the Message Format section for information about the ErrResp format.

If the backend system cannot process the request because it is down, the request message will be discarded by the AMQP server and the client will be notified about it via its return listener.

3.1.4 How to Receive Responses

The client must receive the response asynchronously using a consumer. The client registers a consumer for the response queue, and AMQP invokes the consumer when a message arrives. This method allows the client to wait passively without consuming any CPU. The maximum wait time must be limited, because it is possible that the response will never arrive (see below).

Once a response is received, the client should extract the following message attributes:

• Attribute content-type which contains the XML schema version used for the encoding of the response. This allows the client to choose the correct XML schema for XML unmarshalling. See AMQP Message Properties for information about the formatting of the content-type attribute.
• Attribute correlation-id which contains the correlation ID from the request. This allows the client to match responses with requests. See AMQP Message Properties for information about the formatting of the correlation-id attribute.
• Attribute type which contains the delivered message classname (e.g. ContractInfoRprt). The classname for each message is shown in the Message Properties Summary Table.

3.1.5 Acknowledgement of Responses

The client must not leave any unacknowledged messages on the AMQP server. Client applications are requested to use the auto acknowledgement functionality on RabbitMQ channels to acknowledge the receipt of all response messages as soon as the message has been received (before processing the message).

If client does not receive response in timely manner, it is encouraged to re-inquire for such message as described in Unacknowledged Requests.

If the server side queue gets filled with unacknowledged messages, it might lead to high memory consumption. The private response queues on sthe erver side are constantly monitored and in case one of the queues hit a certain threshold, the connection might be actively disconnected by the server and the Application ID gets deactivated.

Please refer to the Rabbit MQ documentation for more details on the acknowledgement of messages at the AMQP level.

3.1.6 Connection Failure

Clients need to be designed to handle unexpected connection closures. When a connection closes unexpectedly, some requests will not be acknowledged and the client must re-connect and then proceed as described in the Unacknowledged Requests section. It is otherwise not possible to know which requests were processed by the backend, and which were discarded when the connection closed.

It is recommended that clients register a shutdown listener for the AMQP connection to implement this behaviour. The shutdown listener will be called whenever the client detects the connection has closed, regardless of the cause.

Clients must use an exponential back-off when the re-connection repeatedly fails.

3.1.7 Unacknowledged Requests

A request may not be acknowledged because the connection used to send it is closed (see Connection Failure), the request was discarded without being processed, or because the response was discarded. To detect that a message has been discarded, the client must time-out when waiting for responses.

The timeout setting of the client has to take network latency into account. The excessive resending of requests will impact performance.

When a request is unacknowledged, the client must determine if the request was received by the backend.

For non-management requests, it is possible to resend the request to receive the response. You may receive the response more than once. For Management requests, you must send the required inquiry requests to determine if the management request has been executed. If the request has not been executed, you can resend the request.

3.1.8 Message Overflow Handling

If the backend system is not able to process requests (it is not listening on the request queue or it is too busy), the client’s attempts to send request messages will be rejected by the AMQP server (because the messages are sent in mandatory mode).

To detect this, the client must register a return listener for the channel being used to send requests. This is the only circumstance under which the client may assume a request was not processed by the backend. See www.rabbitmq.com for more information about how to register return listeners.

This ensures that most requests are either processed immediately or rejected. Otherwise, client requests could get stalled in the request queue without the possibility to cancel them.

3.1.9 Flow Control

If clients send requests too often, a backlog of unprocessed requests could build up on the server side, resulting in delays in request processing, negatively affecting all of the clients.

Several measures are taken to prevent this scenario.

3.1.9.1 Request Rate Limit

The backend system constantly monitors the request rate of each user and each inquiry request type. For each inquiry message, the backend system defines a short term and long term request limit per user. Currently the short term and long term time periods are set to 1 minute and 60 minutes respectively.

If the number of a specific inquiry request sent by a user within a time period exceeds the configured limit, the backend system will start rejecting this request from that user, until the request rate goes back below the limit. The backend system will send the following error response to the user:

Limit is " + <requestLimit> + " per " + <requestPeriod> + " ms.

When the request rate is exceeded, instead of processing an incoming request, the backend system sends a special back off error response containing details about the length of the measurement period and the request rate limit.

Note that the limits are specified in such a way as to allow a full initial market state inquiry, as well as a ‘normal’ amount of failure recovery. If no failures occur, client applications can remain up to date in respect of the market and reference data by correctly processing the broadcast messages sent by the backend system.

The limits are counted starting with the first request of each particular type.

Example

If the short and long term limits for a message are set to 1 and 10 respectively, the backend system will only allow one request per minute (application of the short term limit). A subsequent request from the same user should thus be sent at least 1 minute after the previous request of the same message type has been sent. In addition, the same request cannot be sent more than 10 times in a period of 1 hour (60 minutes), even if the requests are spaced more than 1 minute apart (application of the long term limit).

3.1.9.2 Message Expiration

Clients may specify an expiration time for each request message. This allows the clients to protect themselves against the situation, when a request waiting in the request queue for a long time becomes obsolete, but eventually gets processed even if the client does not wish to execute the request anymore. If the expiration time has passed and the message has not been consumed from the queue, it’s deleted by RabbitMQ. The RabbitMQ broker uses shorter expiration period of these two: either RabbitMQ default of 45s, or the value set by the client in AMQP Message Properties.

It is not possible to extend the default limit (45s) set by RabbitMQ. The expiration time of the message is the number of miliseconds that corresponds to the difference between the time when the message reaches the AMQP request queue and the time it is consumed by M7 Trading. If the request expires in the queue (expiration time passes before the message can be consumed by M7), it is deleted and no response or broadcast is sent to the client. If M7 consumes a message from a request queue and for some reason crashes before sending the response, the message is lost.

During the management request processing in the core, M7 Trading also follows the expiration set in AMQP Message Properties. If no value is specified by the client, M7 Trading will use a default value of 45 seconds. If the expiration time has passed and therefore the message got expired, it’s not processed by M7 Trading. For this purpose, the expiration time is compared to the timestamp when the message was consumed by PMI Gateway.

During the inquiry request processing, M7 Trading also follows the same expiration time (the expiration set in AMQP Message Properties or a default value of 45 seconds). For this purpose, the expiration time is compared to the timestamp when the message was consumed by M7 Trading inquiry module.

3.1.9.3 AMQP Server Flow Control

In the AMQP protocol, flow control is an emergency procedure used to halt the flow of messages from a peer. It works in the same way between client and server and is implemented by the AMQP Channel.Flow command. Flow control is the only mechanism that can stop an over-producing publisher.

This feature however, is not used by the RabbitMQ server. Instead, in the event that the server hits a preconfigured memory watermark, it uses TCP backpressure to temporarily block all connections that publish messages.

The RabbitMQ server persists the queue contents to disk if required. This allows it to keep more messages than will fit into the machine memory; the queue size is theoretically only limited by the disk space.

In case of very high traffic, the AMQP server can be forced to temporarily throttle publishers to gain time to move some queue contents to disk, releasing memory for new messages. Once this is done, the server will start receiving messages again. (Under normal circumstances, this should not happen because the measures described above should always keep the queues relatively small.)

3.1.10 Message Type

The M7 system uses an AMQP message attribute named type to provide information about the content of each message. Example: ContractInfoRprt

This attribute can be used by a client application to determine the content of each message even before unpacking/processing.

Note: The message type of heartbeat messages is “NULL”.

3.2 Broadcast

The backend system broadcasts three types of information:

• Heartbeat broadcasts sent in regular intervals allow the clients to monitor the availability of the backend system. This is also used to check if clients are still connected to the backend system.
• Market Data broadcasts inform clients about changes within the current market. Traders will only receive information if its assignments are matched by the market data change.
• Reference Data broadcasts inform clients about any changes to the reference data.

Broadcast messages sent by the backend system are distributed (pushed) via the AMQP server to all clients that have subscribed to receive the information.

Several system operations (ex: contract closure, service or delivery areas halt/trading) may generate a large number of broadcasts since they have an impact on reference/market data (ex: contracts or orders state).

The broadcast routing architecture of the backend system

Broadcast messages are encoded and sends using all supported XML schema versions. To avoid supporting too many schema versions and therefore a payload overhead the backend system only supports the latest 2 XML schema versions.

3.2.1 M7 Heartbeat Broadcasts

A durable topic exchange named

• m7.heartbeatExchange

is used for broadcasting heartbeat messages. This exchange is bound to the traders broadcast queue.

The heartbeat messages are sent with a routing key

<schema-version>.m7.heartbeat

Each heartbeat message contains information about the heartbeat interval length, as well as a message attribute within the header property of each message containing the send timestamp called “server-timestamp”. This allows the clients to monitor the availability of the back-end system. An increased message latency indicates a higher system load and/or network delays. See M7 Heartbeat section for information about the heartbeat message format.

The backend system has a connection loss functionality to enable a user to specify actions that will be executed in a failure scenario. If a client has not been connected to the message broker for a specified amount of time (heartbeat timeout defined when client creates connection) the prior defined actions (see Message Format) will be executed and the client will be logged out by the backend system.

Please note the difference between application-level heartbeat broadcasts sent by the backend system and AMQP-level heartbeats:

• AMQP heartbeats are defined by the AMQP protocol specification and allow the client to monitor the existence of a connection between the client and the AMQP server.
• Heartbeat broadcasts published by the backend system are proprietary to the Public Message Interface and allow the client to monitor the availability of the backend system.

The suitable re-connection strategy to be used in the event of a heartbeat loss (e.g. the number of acceptable missed heartbeats) is completely dependent on the third party’s API client implementation.

3.2.2 Market Data Broadcasts

A durable topic exchange is setup per client on the AMQP Server.

• m7.broadcastExchange.<login-id>

The backend system sends messages to the specific trader broadcast exchange whenever a respective action has been performed. Those messages will be delivered to the traders private queue which will be created by the AMQP server according to instructions the client specifies in the initial login procedure.

The private client’s broadcast queue shall be

• created before the LoginReq message is sent
• created by the same connection that is used by the consumer
• created with the x-queue-master-locator parameter set to client-local (this configuration secures efficient message distribution through the RabbitMQ cluster). In case the parameter is not set, the broadcast queue will be created on client’s behalf by the AMQP server and the most efficient message distribution path cannot be guaranteed.
• named m7.broadcastQueue.<login-id>
• configured to that ‘x-message-ttl’ and ‘x-expires’ parameters are set as low as possible

More details can be found in RabbitMQ documentation.

The backend system sends broadcasts messages whenever a change has occurred, either initiated by traders, or the backend system itself. Based on the current data model used in the backend system, different routing keys are used to deliver broadcast messages to the trader’s private exchanges and queue. See the Message Format section to find out what routing key is used by the backend system upon a market data change.

The Broadcast queue is created automatically before the UserReport is sent out. A client can subscribe to broadcasts by binding a consumer to its private queue. Clients cannot subscribe to all existing queues. The access is controlled by configuring privileges for broadcast queues based on the trader’s assignments. If access to a broadcast queue is not granted, the client will not be able to bind a consumer to its private queue.

3.2.3 New Delivery Area Assignments and Broadcasts

When a new assignment of Product or Delivery Area to Balancing group is added, the binding for broadcasts is created dynamically upon this change done in M7 WebGUI.

When a new assignment of Delivery Area to Product (without updating the Balancing group assignemnt) is added, the binding for broadcasts is not created automatically. Users already assigned to the Product in question should log out of M7 Trading and log in again to get the corresponding binding created upon login.

Example

A message (formatted according to schema 6.0) containing information about an order entry done by TM001-BG1——X for product Intraday_Power_D and delivery area 10YDE-RWENET—I will be sent using the routing key:

6_0.Intraday_Power_D.10YDE-RWENET---I.TM001-BG1------X

The message will be pushed to all private queues bound to exchanges using the same routing key.

3.2.4 Reference Data Broadcasts

As each trader has its private broadcast queue, reference data messages will also be sent via the private queue, using specific routing keys. Only messages sent by the backend system that match the routing key will be delivered to the trader’s private queue.

The backend system sends messages to the traders broadcast queue whenever it needs to publish a reference data change to the clients.

A client can subscribe to broadcasts by binding a consumer to its private queue.

Not all traders can receive all broadcasts. For each trader, the access to its private queue is controlled by configuring privileges. If access to a broadcast queue is not granted, the client will not be able to bind a consumer to its private queue.

Example

A message (v6.0 format) containing information about the suspension of trader CXDBSX01 will be sent using the routing key:

6_0.CXDBSX01

The message will be pushed to the trader’s queue that is bound to the exchange using the same routing key:

m7.broadcastQueue.CXDBSX01

3.2.5 Sequence Counting for Broadcast Messages

A sequence number is used to identify the order of the broadcasts and to find out if some broadcasts have been lost. The sequence number is not part of the payload but it is stored within the header of the AMQP message as an attribute called x-m7-group-sequence.

The sequence will be always increased in increments of one for the next broadcast. It will be stored in-memory only (NOT persisted), which means that when the backend system shuts down or terminates, the sequence will be reset to 0 (e.g. in case of a failover event when the original master node went down ungracefully). Whenever the client gets a value which is not expected (i.e. value different than last_value+1) it should request the market data from the backend system.

Rarely, it may happen that client gets a value which is lower than expected but still not necessarily a reason for the synchronization of market data. When the same message is received twice, for example, sequence 11 is received again after sequence 12, it may have been caused by incorrect message acknowledgment on the side of consumer application. In such case, it is safe to ignore the duplicated message, while keeping in mind that a sequence reset as described above may occur.

Note a discontinuous sequence and user disconnection are two independent things, therefore a sequence reset does not necessarily lead to a user being disconnected. A discontinuous sequence indicates inconsistent data, therefore the reaction of the client shall be to perform its re-synchronisation. In case of a sequence reset, all sequence IDs will be reset to 0.

The sequence number is counted based on the routing keys (attribute x-m7-group-id in message header). For each routing key there will be a different sequence number. All queues that are bound to the default broadcast exchange with the same routing key will receive the same sequence id. The order of broadcasts are guaranteed only on the level of routing key or the attribute x-m7-group-id. M7 or RabbitMQ does not guarantee any sending or reception order of messages across several routing keys.

3.2.6 Gap Detection and Acknowledgments

Gaps are an inherent part of the communication protocol. They can occur under some conditions and clients have to be able to recover from them.

The recovery can be done in the following ways:

• A complete disconnection and re-connection to RabbitMQ;
• A new request for the missing data by an inquiry request on the existing RabbitMQ connection. Please see Event-index for instructions on the recommended inclusion of event-index property.

Gap occurrence conditions:

• slow consumer (broadcast queue has configured time to live before timeout)
• broker restart/fail-over (more about failover in AIP130 - Application Failover)
• connection loss
• client failures

Client libraries often contain a so called auto-recovery mode which will not propagate connection errors to upper layers but will seamlessly reconnect to broker. Under those circumstances, gaps will occur because of connection loss and no error is reported. So clients should take this under consideration or have auto-recovery disabled.

3.2.7 Broadcast Distribution from M7 Back-End to AMQP Server

All broadcasts from M7 back-end to AMQP server may go through one or multiple separate connections. The distribution of broadcast messages into each connection is performed based on the routing key. These include for example:

• Several connections for broadcasts with the routing key containing the string .prddlvr. (i.e. Public Order Books Delta Report);
• A connection for member;
• A connection for balancing group;
• A connection for heartbeats. The heartbeats are sent through the dedicated connection in order to minimise the risk of slowing down their delivery.

For the ordering of the broadcast messages please refer to the chapter Sequence Counting For Broadcast Messages.

Please note the information contained in this paragraph is for informative purposes only and may be subject to changes. This includes also the number of connections used for the broadcast distribution from the M7 back-end to the AMQP Server as well as the distribution rules for each such connection.

3.2.8 How to Receive Broadcasts

As the trader’s private broadcast queues are durable queues and are already set up in the AMQP Server any client that wants to subscribe to broadcasts simply registers a consumer for its private queue.

Whenever a message is broadcast by the backend system, a copy of the message will be placed into the trader’s private queue and the client’s call back method will be invoked on the registered consumer.

To stop receiving broadcasts, the client should remove the consumer from its private queue.

The broadcast queues within the AMQP Server are set up as durable queues to avoid the loss of any messages due to connection problems. The broadcast queues are also configured with a time to live for messages that are put into the queue (e.g. 60 seconds). This will protect the AMQP Server from out of memory issues in case a client consumes the messages too slowly or because of any other connection problems.

3.2.8.1 Broadcast Queue Expiration Time

Besides the time to live for messages waiting inside the broadcast queue, a time to live parameter for the existence of broadcast queues themselves is configured (“broadcast queue expiration time”) to protect the AMQP server from memory issues.

If no consumer is declared for the queue in question, i.e. no client is consuming/using the queue, it gets deleted by the AMQP Server after the time to live expires.

The current broadcast queue expiration time is set to 180 seconds.

3.2.8.2 Event-index in Broadcasts

M7 includes the value of event-index message property in all broadcasts. For more details, please see Event-index.

3.2.9 Re-login after Unexpected AMQP Disconnection

In case of an unexpected AMQP disconnection (e.g. due to network issues), the client is able to reconnect and start consuming from the existing broadcast queue before it reaches the end of the expiration time.

It is recommended to start consuming from the broadcast queue right after having logged in (i.e. right after the reception of the UserRprt).

This action should be taken before or in parallel with the action of sending inquiry requests and/or processing the corresponding responses to minimize the risk of losing the broadcasts present in the queue when it reaches the end of the expriration time.

3.2.10 Acknowledgement of Broadcasts

The client must not leave any unacknowledged messages on the AMQP server. Client applications are requested to use an auto acknowledgement on RabbitMQ channels to acknowledge the receipt of all response messages, as soon as the message has been received (before processing the message). It is strongly recommended to implement a gap-detection mechanism as described in chapter Sequence counting for Broadcast Messages to prevent any data-loss.

If the server side queue gets filled with unacknowledged messages, it might lead to high memory consumption. The private broadcast queues on server side are constantly monitored and in case one of the queues hit a certain threshold, the connection might be actively disconnected by the server and the Application ID gets deactivated.

3.2.10.1 Auto Acknowledgments

This is the preferred variant of acknowledgments because it provides higher throughput. Messages are reliably transferred from broker to client via TCP but client does not send explicit AMQP acknowledgments (this saves the line).

3.2.10.2 Manual Acknowledgments

In this mode an AMQP acknowledgment is sent after every message (or after every batch) by client. Broker tracks number of unacknowledged messages. When unacknowledged and new messages reach the configured threshold of messages then client is disconnected from broker because it threatens broker’s stability.

An important point to note is that unacknowledged messages are sent after reconnect (when broadcast is not deleted yet). Those messages have the re-delivery flag set to true and are mixed together with new messages so the sequence numbers seems to not be continuous. Client has to deal with this and not treat it as gaps.

3.2.11 Failover Processing

In case of an AMQP server shutdown (due to a failure or restart), the client subscriptions are lost. If the client has registered a shutdown listener, it will receive a shutdown notification from AMQP. After successful reconnect to the AMQP server, the clients have to re-subscribe.

In case of a backend system failure, the client subscriptions will stay active, but clients will not receive any broadcasts until the backend system is restarted. Once the backend system is restarted, delivery of broadcasts will resume without any further actions being required on the client side. The client will recognise that the backend system is down because no more heartbeat broadcasts will be sent. Note that in the case of a backend restart, the sequence numbering for the requests will be restarted.

Any broadcast messages published by the backend system whilst a client was disconnected, will be lost for that client if the client does not reconnect within the specified time to live time for the messages within the queue.

3.2.12 Flow Control

When a client is consuming messages too slowly, a backlog of messages waiting for processing may build up in the private queue(s) owned by this trader.

If messages exceed the time to live limit, the AMQP server will start deleting those messages from the trader’s private queues. Thus, a slow client may lose messages.

The clients are therefore required to consume and acknowledge each message as soon as possible. If the processing of a message is a non-trivial task, the receiver must handle the receipt of the message separately from the actual processing of the message: the message must be consumed, acknowledged and stored in a memory buffer of the client, where it awaits processing.

It is important that clients consume messages as quickly as possible. Should a client fail to adhere to these rules and consume messages too slowly, it may lose messages and display a non-up to date market state.

3.2.13 Message type

The M7 system uses the AMQP message attribute named type to provide information about the content of each message. Example: ContractInfoRprt.

This attribute can be used by a client application to determine the content of each message even before unpacking/processing.

4 Security

All communication between the client and the AMQP server is encrypted using the Transport layer security (TLS) version 1.2 only. Older TLS versions are not supported anymore. Client and server certificates are used to establish a trusted connection. The usage of asymmetric encryption ensures confidentiality, authentication, message integrity assurance and non-repudiation of origin.

4.1 Server Certificate

The backend system uses signed Server Certificates.

Usually the CA root certificates are known and trusted by the software development frameworks like Java or .NET. If not, clients need to add the CA root certificate to a list of trusted certificates. The needed CA root certificate files can be downloaded directly from the CAs Website².

The exact way this is done depends on the platform and programming language in which the client application is developed. Please note that the CA root certificate has to be imported into a location used by the client application's runtime environment, not into a web browser.

4.1.1 Using CA Root Certificate in Java

For Java clients, the CA root certificate must be imported into a keystore, which will be used to initialise the Trust Manager used by the client application. The certificate can be imported using the keytool utility, which is part of the Java runtime environment:

keytool -import -alias m7-ca -file <cacert> -keystore <keystore>

In the command above, <cacert> is path to the CA certificate file in PEM format (cacert.pem) and <keystore> is path to the keystore file. You have to confirm that you trust the certificate being imported.

The keystore file will be created if it does not exist already. Java keystores are protected by a password; choose a password when first creating the keystore and then use it whenever accessing the keystore.

Please refer to Java documentation for more information about the keytool utility.

4.2 Client Certificate

An organisation that wants to use the Public Message Interface of the backend system has to apply for an account on the AMQP server. The following is provided when a new account is set up:

• AMQP server host names, port number and virtual host name.
• The trader’s login ID if it doesn’t already exist.
• A client certificate and private key that will be used by the client when connecting to the AMQP server.
• A CA root certificate that has to be imported as a trusted certificate on the client side.

The client certificate:

• complies to the X.509v3 specification,
• uses a key length of 2048 bits,
• subject contains an unique identifier as the Common Name,
• is signed by Deutsche Börse CA,
• is provided in format PKCS#12 (.p12).

The client's private key is used to verify the client's identity when communicating with the AMQP server. Should a third party get hold of the client's private key, it could forge client's identity and access the encrypted communication with the server.

It is therefore extremely important to keep the private key secure.

4.2.1 Using a Client Certificate in Java

To be able to use the client certificate and private key in a Java client, they need to be loaded into a keystore, which is used to initialise a Key Manager. Java supports the PKCS#12 format (.p12), where the private key is protected by a passphrase. The passphrase is provided to the client along and it must be used when loading the .p12 file into the keystore.

For further details regarding TLS security, please consult the TLS specification, AMQP specification and https://www.rabbitmq.com/ssl.html.

4.2.2 Usage of ComTrader Certificates

The ComTrader certificate is strictly intended for use with the ComTrader frontend client. Any other use of the ComTrader certificate, including but not limited to its application in production environments with third-party APIs, is strictly prohibited.

It is imperative that all members adhere to the following guidelines:

Authorized Use: The ComTrader certificate must only be used with the ComTrader frontend client.

Prohibited Use: The use of the ComTrader certificate for any other purpose, including integration with third-party APIs, is forbidden.

All members must comply with this policy to ensure the integrity and security of the system. Failure to adhere to these guidelines may result in disciplinary action and revocation of access privileges.

4.3 Authentication

4.3.1 General

When a client connects to the AMQP server using the TLS protocol, both peers are mutually authenticated by exchanging their certificates during the TLS handshake. All subsequent communication between the client and the server is encrypted using the cipher agreed on during the handshake. To create a connection to the AMQP Server, the username and password are required. The AMQP Server is connected to an internal LDAP Server which will verify the given credentials. In case of an unsuccessful authentication the client won’t be able to connect to the AMQP Server.

Whenever a client sends a request to the AMQP server, it uses a client-specific exchange. The exchange name contains the client login id, which can be extracted by the backend system when processing the request to identify from which client the request came.

4.3.2 Cipher Suites Supported by the M7 Trading application for API connection

As mentioned previously, after the TLS handshake the entire communication between the client and the AMQP server is encrypted.

The M7 Trading application currently supports the following cipher suites for the API connection:

• ECDHE-ECDSA-AES256-GCM-SHA384
• ECDHE-ECDSA-AES128-GCM-SHA256
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-RSA-AES128-GCM-SHA256
• DHE-RSA-AES256-GCM-SHA384
• DHE-RSA-AES128-GCM-SHA256

Disclaimer: The above-mentioned list is based on the last penetration test performed by DBAG in November 2020 and may be subject to change. Any modifications to the list triggered by DBAG will be announced with sufficient lead time, whenever the situation allows it (an example of an exception would be the installation of a security patch).

Nevertheless, it is important to note that also upgrades of the OS and the SSL library may result in some (but not all) of the above listed ciphers not being supported for establishing the communication with the M7 Trading application via API. As DBAG cannot influence the project lifecycle of the third parties’ software, it strongly recommends all AMQP clients to perform a simple connectivity test to verify that the connection with the AMQP server can be established. Such test should be executed at least once for each major release (6.11, 6.12 etc.) during the release UAT phase, to prevent later connectivity issues in a Production environment.

4.4 Authorisation

Authorisation of client actions occurs on two levels.

4.4.1 Authorisation by an AMQP server

The AMQP server verifies client’s privileges when a client accesses resources stored on the AMQP server. This includes exchanges and queues that the client tries to configure, read or write. This applies to:

• binding queues to private broadcast exchanges
• sending messages to request exchanges

In case of insufficient privileges, the attempt to access the resource is immediately (synchronously) rejected by AMQP.

4.4.2 Authorisation by the Backend System

The backend system verifies privileges when processing requests from clients.

In the event of insufficient privileges, the request is rejected by the backend system. From the client point of view, this rejection occurs synchronously for inquiry requests as a negative response message is sent to the traders response queue and asynchronously for management requests as a negative response message is sent to the traders private exchange using the routing key <schema-version>.trdr.<login-id>.

5 Message Format

All messages sent between the backend system and clients have an XML-encoded payload and specific AMQP message properties. This section describes the xml payload format and the AMQP message properties in detail.

The xml payload format specification comes in the form of XML schemas, which specify the allowed structure and format of XML elements and attributes. These are covered in the section 6 Public Requests and Responses and 2 Admin Requests and Responses in DFS180a.

5.1 General Information

5.1.1 AMQP Message Properties

The following message properties must or can be set when sending a request to M7:

5.1.2 Message size restrictions

• Message body with headers is restricted to maximum size of 41 943 040 bytes of uncompressed size.
• Message body is restricted to maximum size of 40 894 464 bytes of uncompressed size.
• Message with headers is compressed by gzip. If it exceeds 2 621 440 bytes the message will be rejected.

5.1.3 XML Convention

• Element tags are only used for structure reasons.
• Data is only carried in attributes, never in element tags.
• Types:
  • All Elements are bold, Attributes are in regular text
  • SE: Structure Element. No Data embedded between tags, but it may contain attributes. Contains no data. (grey background and bold)
  • CE: Content Element. Data is embedded between tags, and can also contain attributes.(bold)
  • A: Attribute of an Element.
• The sorting of elements and attributes is not guaranteed and might change in the future.
• The m/o column specifies if the presence of the element/attribute is mandatory or optional

5.1.4 Standard Message Header

Every message will contain a header at the beginning of the message.

Table 2: Message layout of the Standard Message Header.

5.1.5 XML Validity and Data Binding

It is important that clients produce valid XML code when sending requests to the backend system. The backend system uses a validating parser which rejects any requests that do not strictly conform to the supported XML schemas.

To make parsing and the creation of XML data easier, and to avoid problems with the validity of the XML code, clients are encouraged to use XML data binding.

5.1.6 XML Schema Version (content-type)

Every message sent or received by the backend system must specify the XML schema version that was used to encode its payload in its metadata. This information is stored in the message properties in the content-type field as a string.

The content-type should contain value that corresponds to the major schema version.

This information can be used to validate that both peers use the same version of the payload format. The backend system rejects requests with an unexpected schema version.

Example

For XSD schema version 6.15.40, the major XSD schema is 6.0.

5.1.7 App-version

In the app-version, the client may provide the version of the application being used for its connection to the M7 Trading system.

If the app-version is provided, M7 validates that:

1. It is higher than or equal to the minimum version for the given app-id.
2. Its format is either an integer number, or multiple integer numbers separated from each other by a dot sign (“.”).
   Example: app-version=10 or app-version=4.1.5
3. It is at most 32 characters long.

In case the app-version fails at least one of the above validations, the connection is refused.

If an app-version is not provided, the check is not performed and the connection is allowed.

5.1.8 Event-Index

As of M7 6.16, M7 introduces an event-index message property.

event-index is a header attribute which enables M7 to track asynchronous market events among M7 components. In this way, M7 can provide better performant responses to clients’ inquiry requests.

event-index increases every time M7 processes an event, e.g., order entry, contract opening or closing, both in LTS or XBID market or delivery area halt. The system sends the latest value of event-index in the market first in UserRprt after client’s login, and then with every broadcast.

M7 6.16 is the earliest version supporting this property, however, please note its activation is exchange-specific. There are no consequences for clients not to use it, whether it has been or not activated on the M7 side.

General Information

event-index is an optional attribute in contentHeader, type Long.

Its value is always increasing, but not necessarily sequential as not all events are relevant to all users due to their assignments.

Depending on the value of event-index the following behavior is expected:

1. Event-index(request) =< Event-index(market) –> The system sends the latest data.
2. Event-index(request) > Event-index(market) –> If after three self re-inquiries the event-index wasn’t processed the system sends a timeout error, see DFS200 - 4.2 General errors, Error ID: 2095.
3. Event-index(request) < 0 or not a Long data type –> The system defaults the event-index to 0 and sends the latest data.

Inquiry requests that currently support event-index attribute: TradeCaptureReq, PblcTradeConfReq. The list of inquiry requests supporting the property will be gradually extended in future M7 releases.

As the attribute is optional the client should be able to receive inquiry responses both with or without the event-index.

Use of Event-Index During Login Procedure

When logging into M7, as a response to LoginReq, the client receives the UserRprt which has the current value of event-index in the market.

The client should use this value in inquiry requests to get the initial set of the market and other information necessary to start a trading session. Usage of the event-index value from the UserRprt assures that clients get the latest market data available in the system.

Use of Event-Index in Gap Detection

In case the client detects a gap in a broadcast sequence, see Sequence Counting for Broadcast Messages, the value of an event-index from the latest broadcast can be used to re-inquire a request. Thus, M7 activates a new, more performant component to process the request.

Therefore, it is advised to start including the value of event-index in each inquiry request sent to M7 to get a quicker response.

5.1.9 Metadata

Starting from version 6.19, selected messages will include additional metadata within their headers. This metadata is intended for internal technical purposes and is not designed for end-user interaction. This feature is implemented to enhance the internal handling and processing of messages. Users are not required to interact with or modify this metadata. This metadata attribute is specific to the exchange.

The metadata consists of a base64-encoded byte array: headers={..., metadata=N3hFeL+UKhErusxFLkrpYVYvcH6vXNtIGzQT5lbV, ...}

5.1.10 Server-timestamp

The server-timestamp header is set by core in the moment when the message is converted to external format (Core Sender time)

5.1.11 PMI-processing

The pmi-processing header, set by the PMI Gateway, records the time taken to process an OMT message and send an acknowledgment response (AckResp). This header is used for monitoring purposes.

5.1.12 M7 Heartbeat

The heartbeat contains the message SYSTEM_ALIVE:<interval> and the message attribute “server-timestamp” within the header property of each message.

In case the message with the interval has not yet been received, the client shall wait for 5 seconds to receive the M7 back-end heartbeat after its first connection to the broadcast queue.

5.1.13 Quantity Values in Messages

Quantity values in all messages (requests and responses) are given as integer values which represent exactly the database values stored in the backend. The interpretation/display of these values depends on the product attributes decShftQty, minQty and qtyUnit (see Product Information Report).

The attribute decShftQty defines the position of the decimal point within the integer value (e.g. the integer value 1000 with a decShftQty of 3 means a decimal number of 1.000).

The attribute minQty defines the possible quantity steps which can be entered into the system and at the same time the smallest possible quantity value (e.g. a minQty of 100 means, quantities can be entered in 100 steps starting with 100: 100, 200, 300, etc. - the value of 50 would be rejected). The minQty can also be used to limit the number of displayed decimal places for a quantity value: With a minQty of 100, the last two zeros might be cropped when displaying quantities, because they are always zero.

The attribute qtyUnit contains a string with the unit of the quantity values (e.g. “MW” for megawatt in the power market).

Table 3 shows some examples.

Table 3: An example of displaying quantity values

5.1.14 Price Values in Messages

Price values in all messages (requests and responses) are given as long values which exactly represent the database values stored in the backend. The interpretation/display of these values depends on the product attributes decShftPx and currency (see Product Information Report).

The attribute decShftPx defines the position of the decimal point within the long value (e.g. the long value 1276 with a decShftPx of 2 means a decimal number of 12.76).

The attribute currency contains a 3 character long identifier for the currency. A decShftPx of 2 for the currency Euro means that the values are given in Eurocents (3499 = 34.99 EUR = 3499 Eurocents).

5.1.15 Date Time Values in Messages

Date time values in messages (data type in the message layout tables is “DateTime”) are given as XML Schema DateTime values in the following format:

YYYY-MM-DDThh:mm:ss.sssZ (2023-09-14T12:34:23.351Z)

All Date/Time values are given in the UTC time zone. To get local times, the client has to add or remove hours based on the local time zone.

Contract naming patterns are affected by the time zone set at the product level.

The market time zone can be obtained using the SystemInfoResp message (see System Info Response).

5.1.16 Date Values in Messages

Date values in messages (data type in the message layout tables equalling “Date”) are given as a Date value in ISO format:

YYYY-MM-DD (2023-09-24)

5.1.17 On-behalf Trading

• On-behalf trading on a member level: Traders having the right to trade on-behalf are allowed to perform actions for all traders belonging to the same balancing group.
• On-behalf trading on a broker level: Broker users are allowed to trade on-behalf for all traders that are assigned as the assigned members for their account regarding the user product configuration.
• On-behalf trading on an admin level: All Admin users are allowed to trade on-behalf for all traders in the system. In relation to the user product configuration (only products assigned to the trader can be traded on behalf even if the admin user itself has a wider assignment of products).

In order to submit requests to the backend as on-behalf requests on a broker or admin level, the standard message header field onBehalfUserId must be filled in with the user ID of the target user, for whom the request is sent on-behalf (see Standard Message Header). For on-behalf requests on a member level, the submission of the user Id of the target user ID is not required.

Although the standard message header is part of every message in the Public Message Interface, the field onBehalfUserId is only relevant for the following request types:

• Order Entry Request (OrdrEntry)
• Order Modify Request (OrdrModify)
• Order Request (OrdrReq)
• Order Execution Report (OrdrExeRprt)
• Trade Recall Request (TradeRecallReq)
• Message Request (MsgReq)
• Message Report (MsgRprt)
• Trade Capture Request (TradeCaptureReq)
• Trade Capture Report (TradeCaptureRprt)
• Order Limit Request (OrdrLmtReq)

If the field is filled in for a request, which does not support on-behalf trading, it will be ignored by the backend.

In case of an on-behalf request, the user with the onBehalfUserId will be retrieved on the backend side and the user context of the request is changed to this user. This means that the request is treated by the backend like a normal request directly from the user.

5.1.18 Message Properties Summary Table

The description for every message starts with a table that summarises the key properties of the message. The following table describes the different properties and their meaning:

The message classname is present in the table header.

5.1.19 Any Elements and Attributes

For forward compatibility reasons each entity in PMI is now expandable with any element and anyAttribute in the XSD schema. For more details please refer to chapter Forward compatibility.

6 Public Requests and Responses

The requests and responses described in this chapter are used for users without administrative privileges in order to communicate with the backend.

6.1 General Requests and Responses

The general requests and responses described in this chapter are used to login and logout of the backend system as well as for responding to management requests.

6.1.1 LoginReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: All
• Request Limits: 14/70

The Login Request is sent to the backend system to participate in the market. As a response to this request either User Report(=a successful login) or Error Response is returned.

Error Response might indicate that a trader with the same credentials is already logged into the backend system.

Login Request has to be sent at least 5 seconds after a successful Logout Request.

6.1.2 LogoutReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: All
• Request Limits: 14/70

The Logout Request has to be sent by a client application if the trader logs out of the backend system manually. The queue deletion or channel closing is handled by the backend system. The maximum amount of time needed for Logout Request associated activities (e.g. RabbitMQ queue deletion) is 5 seconds.

6.1.3 LogoutRprt

• Type: Inquiry Response; Broadcast
• Response to: LogoutReq (sent to the private response queue)
• Roles: All
• Broadcasted: Yes
• Broadcast Routing Keys: [schema-version].trdr.[user-id]
• Broadcast Audience: Only the user with the usrId involved

The Logout Report is used:

• As a response to the Logout Request (to the private autogenerated response queue) in which the attribute usrId and sessionId will be set to respective values.

• As a broadcast Logout Report to the user who is logged out as a consequence of a concurrent forced login with the same user credentials. The attribute forced is set to ‘true’ (routing key:[schema-version].trdr.[user-id]). The usrId and sessionId will be set respectively in this case as well.

• As a broadcast in case of any other event leading to the logout of the user.

6.1.4 SystemInfoReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: All
• Request Limits: 14/70

The System Info Request is used to get general information about the backend system.

6.1.5 SystemInfoResp

• Type: Inquiry Response
• Response to: SystemInfoReq (sent to the private response queue)
• Broadcasted: No
• Routing Keys: –
• Roles: All

The System Info Response returns general information about the backend system as reply to a System Info Request.

6.1.6 AckResp

• Type: Management Response
• Response to: OrdrEntry; OrderModify; ModifyAllOrdrs: TradeRecallReq: (sent to the private response queue see Request-Response communication)
• Roles: Trader, Market Operation, Broker, Sales
• Broadcasted: No
• Broadcast Routing Keys: –

The Acknowledgement Response is sent upon receipt of a management request. If an acknowledgement response is not sent, the client has to send an inquiry request to figure out if the previously sent management request has been executed.

The response is sent back using the same correlation id within its message attributes. Acknowledgement Responses are always sent to the private response queue of the client. If the system detects an error which prevents it from processing of the message (a syntactical error but also if the message content is against the M7 Trading documentation, e.g. if a buy ICB order has a positive peak price delta), it may reply directly with an ErrResp instead, sending it to the private response queue of the client.

If no errors were detected as described in the previous paragraph, M7 immediately acknowledges the request message being forwarded to Core for processing via AckResp message. This acknowledgement confirms successful message sending, not Core receipt. Because the PMI Gateway generates the AckResp, it may be omitted in rare instances (e.g. in case of a PMI Gateway restart), even is the message was successfully sent to the Core.

In rare circumstances, a Core system failover can occur after the PMI Gateway has sent the request and the acknowledgement (AckResp) has been issued. If this happens, the request might not be processed even though the client has already received the AckResp. In such cases, if you do not receive a message containing the results of the requested operation within a reasonable amount of time, please verify the status of your data by submitting the appropriate inquiry request.

Note: Because of new architecture constraints, clOrdrId has been removed from this message.

6.1.7 ErrResp

• Type: Inquiry Response; Management Response; Broadcast
• Response to: All (sent to the private response queue)
• Roles: All
• Broadcasted: Yes
• Broadcast Routing Keys: [schema-version].trdr.[user-id]
• Broadcast Audience: The connected users whose action caused the asynchronous error (i.e. OrdrEntry whilst not having a sufficient cash limit).

The Error Response is sent whenever the M7 Trading system determines a business exception has occurred, based on wrong entries in the request.

Error Responses can be sent synchronously or asynchronously (broadcast). The M7 Trading system sends the Error Response in a synchronous way whenever the received XML message contains syntactical errors or if the message content is against the M7 Trading documentation (e.g. if a buy ICB order has a positive peak price delta). In this case, the requests have not been processed by the M7 Core yet. Error Responses are sent by the M7 Core in an asynchronous way if any errors happen during processing of the request (e.g. if an order is submitted for an expired contract). Synchronous Error Responses get sent to the trader’s private response queue, asynchronous get sent to the trader’s private broadcast queue.

Any connected application may use English text provided in the “err” attribute, or can use the provided text resource with the transferred variables. This way the localisation of the error text can be completed on the client side (the server side provides no localisation in the err texts).

Example of ErrResp

<Error errCode="12345" err="ACCT1 - account not found">
  <VarList>
    <Var id=“0” value=”ACCT1”/>
  </VarList>
</Error>

Provided resource file contains:

The client application can either use the err attribute from the message which will always be in English, or it can use the provided resource file to translate to any other language and fill the provided variable itself.

6.1.8 ChgPwdReq

• Type: Management Request
• Routing Keys: m7.request.management
• Roles: All
• Request Limits: 1/10

This message can be used by any user to change his password. It is not possible to change a password on behalf.

AckResp (confirmation that ChgPwdReq was received) is sent, and as a result, one of following actions is performed:

1. ErrResp: The change of password was not successful. The err attribute will contain a detailed error message from LDAP/M7.
   
2. If the change was successful, a shutdown signal from the broker with the reason PWD_CHANGE and second AckResp (confirmation that password was changed) are sent. Note that shutdown signal might be sent before or after second AckResp. The user then can re-login with the new password.

The password must comply with the LDAP server password policy; otherwise, an error message from LDAP will appear in the err attribute.

New password shall be different than 6 previously used passwords (this is configured in LDAP settings). In addition, the password must not contain 3 or more consecutive characters from the user’s LoginId (the check is case-insensitive). Passwords shall be at least 8 characters long and shall fulfil 3 out of the 4 requirements:

• At least one upper case letter
• At least one lower case letter
• At least one number
• At least one special character.

Passwords can expire after a certain length of time³ according to the LDAP settings. If the expiration time is configured in LDAP, M7:

• sends a reminder to the e-mail address set in the user’s profile in M7 Admin GUI X⁴ days before the password expiry, informing the user about the expiration date,
• sends a notification on the day of password expiry, containing a link to the password reset page.

6.1.9 TotpPwdReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: All
• Request Limits: 14/70

This request can be used by any user to regenerate the time-based one time key.

This request is followed by a TotpPwdResp sent as a response.

6.1.10 TotpPwdResp

• Type: Inquiry Response
• Response to: TotpPwdReq
• Broadcasted: No
• Routing Keys: -
• Roles: All

The TotpPwdResp returns the newly generated secret key which will be used as an input key for the account registration in the user’s personal Authenticator (generator of one time passwords).

6.2 Order Entry and Maintenance

The messages described in this section are used to enter and maintain orders. These messages can be used only by trading participants and are not available for Market Operation users.

6.2.1 OrdrEntry

• Type: Management Request
• Routing Keys: m7.request.management
• Roles: Trader, Market Operation

The Order Entry message enables a trader to send up to 100 orders at once to the backend for execution. The orders are contained in a so called basket. It is possible to define the execution restriction on a basket level.

The message flow is shown in the below figure ⁵:

Note: Actions caused by partial or full execution or invalid order parameters are not part of this diagram.

At least one acknowledgement (AckResp), exactly one Error Response (ErrResp) containing the information on the error(s) or one Order Execution Report (OrdrExeRprt) is sent back, even if the OrdrEntry request contains several orders.

In case of order executions (trades) public and private messages will be broadcast (PblcOrdrBooksDeltaRprt). In addition to the OrdrExeRprt, a Trade Capture Report will be sent to the affected parties, the public order books will be updated (giving rise to Public Order Books Delta Reports), and the connected data vendors will also receive updated data.

A Cash Limit Delta Report is sent only in case the order entry has an impact on the cash limit, otherwise the message is not sent.

6.2.2 OrdrModify

• Type: Management Request
• Routing Keys: m7.request.management
• Roles: Trader, Market Operation

This message is used to modify one or several orders. If the order modification has an impact on the order execution priority, the old order is removed by the system and a new order with a new order id is entered instead. As a result, after an order modification is made which has an impact on the execution priority, an OrdrExeRprt message containing two records is sent:

• One record details the deletion of the order that was present in the system before the modification.

• Another record details the the addition of a new order that was just created in the system to reflect the modification.

Due to performance optimisation, the order of the above two records in the OrdrExeRprt is not given (the deletion of the old order can be before or after the addition of the new one).

Note: For remote orders, the behaviour of OrdrExeRprts may be different than described, as it depends on the processing of the OrdrExeRprts by XBID.

The message flow is shown in the below figure:

6.2.3 OrdrReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: Trader, Market Operation
• Request Limits: 1/10

The Order Request is used to request all own orders, which are currently active, hibernated or in unknown (UKNW) state for the given account and products. The Order Request is acknowledged by an Order Execution Report.

The message flow is shown in the below figure:

6.2.4 OrdrExeRprt

• Type: Management Response; Broadcast
• Response to: OrdrEntry; OrdrModify; OrdrReq; ModifyAllOrdrs; (sent to the private response queue)
• Broadcast: Yes
• Routing Keys: [schema-version].bg.[acctId], [schema-version].loc.[prodName].[dlvryAreaId]
• Broadcast audience: Trader (owner of the order) and traders from his Balancing groups, Admins, Brokers with an assignment to Trader (owner of the order).
• Roles: Trader, Market Operation

The Order Execution Report is sent in the following cases:

• After a successful Order Entry.
• After an Order Modify request.
• After a partial or full execution of the order.
• In case of the execution of a Pre-arranged order.

As a response to an Order Request, the Order Execution Report is sent to the private response queue of the requesting user.

In both cases, traders will receive only the orders entered in the account they are assigned to, whereas market operations users will receive all orders.

If Locations are enabled for the product (i.e. product matcher type is Energy Location-Price-Time or Energy Location-AON), the OrdrExeRprt for the product’s orders is broadcasted also to Redispatch Balance Users, using the routing key [schema-version].loc.[prodName].[dlvryAreaId]. In such case, Redispatch Balance Users are notified about orders submitted for assigned products and assigned delivery areas, regardless of the assignment for balancing group. That is, Redispatch Balance Users receive broadcasts for all existing balancing groups. If an order is submitted for a balancing group assigned to the Redispatch Balance User, they will receive two OrdrExeRprts with the same revisionNo, one for each routing key. Redispatch Balance Users should ignore the second broadcast with the same revisionNo. This situation is depicted in the schema below.

6.2.5 ModifyAllOrdrs

• Type: Management Request
• Routing Keys: m7.request.management
• Roles: Trader, Market Operation

Modify All Orders message is used to activate, deactivate or delete all orders belonging to an account or a trader or deactivate all orders belonging to a member. Only one of the attributes mbrId, usrId or acctId must be filled with a proper value. In case of an account, also specific products can be defined to be taken into account.

The message flow generated by this request is depicted in the following diagram:

6.2.6 OrdrLmtReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: Trader, Market Operation, Broker, Market Maker

The OrdrLmtReq is used to retrieve the current Order Limits valid for the member to which the logged in trader is assigned.

6.2.7 OrdrLmtRprt

• Type: Inquiry Response; Broadcast
• Response to: OrdrLmtReq (sent to the private response queue)
• Broadcast: Yes
• Routing Keys: [schema-version].mbr.[mbrId]
• Broadcast audience: All traders from particular member, Admins
• Roles: Trader, Market Operation, Broker, Market Maker

The OrdrLmtResp is returned as a response to the OrdrLmtReq or as a broadcast as a result of an event that changes an Order Limit. The message lists all the Order entry limits of the inquired member. These limits are then checked at every order entry process for appropriate member.

6.3 Trade Maintenance

6.3.1 TradeRecallReq

• Type: Management Request
• Routing Keys: m7.request.management
• Roles: Trader, Market operation

This message is used to request a recall of a miss-trade. Market Operation will be informed about the trade recall request after successful submission.

The message flow is shown in the below figure:

The message required for a trade recall request contains only the trade identifier and revision number of the affected trade.

Note: if trade for which recall is requested has filled parentTradeId, the trade with tradeId=parentTradeId and also all other trades with the same parentTradeId will be recalled simultaneously.

6.4 Market Information

6.4.1 Retrieval of Public Order Book information

The public order book of a contract is built up by performing the following steps:

• Retrieve the initial data set at the start of a user session, using the Public Order Books Request (PblcOrdrBooksReq). All active orders in the order book at time of request are returned.

• During the session, process the Public Order Books Delta Responses (PblcOrdrBooksDeltaRprt) that contain all of the updates to the order books.

PblcOrdrBooksDeltaRprt messages with an order book revision number smaller than the ones received in the PblcOrdrBooksResp must be ignored.

6.4.2 Order Book Batching

6.4.2.1 Background

The M7 Trading system has been designed to operate in the 24/7 mode.

Market activity is increasing continuously and one of the impacted areas is the order books. During periods of heightened market activity called “peaks”, the system must be able to process and distribute a significant number of order book delta (OBK delta) messages in a timely manner.

It is important to highlight that the number of OBK delta messages to be processed and distributed does not only include the messages produced by the M7 LTS itself. It also includes the OBK delta messages received through the XBID solution due to the trading activity of other power exchanges.

6.4.2.2 Order Book Batching

To smoothen the hightened trading activity, M7 Trading application features Order Book Batching (OBK Batching) mechanism which enables the system to optimise the way the OBK delta messages are built and the frequency of their distribution to M7 users.

When OBK Batching is enabled, the system is collecting OBK delta messages during the configured Batch interval. At the end of the Batch, it bundles these messages into one “batched” OBK delta message, which is then distributed to all connected M7 users. Users always receive one batched OBK delta message per Routing Key.

The batching mechanism is available only for V6 OBK delta messages.

6.4.2.3 Batching Mechanism

The OBK Batching mechanism works as follows:

• the Start of a Batch is triggered by an incoming OBK delta message for any Routing Key.

  • when a Batch is not running and OBK delta message is produced for any Routing Key (= Product X Delivery Area combination), then this OBK delta message is sent immediately to M7 users. At the same time, this OBK delta triggers the Start of the Batch.
  • when the Batch is running and there is OBK data to be batched, then a batched OBK delta message is sent at the End of the Batch (see below). At the same time, this triggers the Start of a new Batch.
  • when the Batch is running and there is no OBK data to be batched, then no OBK delta message is sent at the End of the Batch (see below). As there is no OBK delta sent out, there is no trigger to Start a new Batch.

• the End of a Batch is triggered by

  • the end of time interval configured for the Batch (LONG or SHORT), OR
  • a PblcOrdrBooksReq received and successfully processed for any Routing Key, i.e. (Product X Delivery Area combination).

The OBK Batching mechanism is depicted by the following diagram:

Notes:

• Both LONG and SHORT running batches are stopped whenever a PblcOrdrBooksReq is received and successfully processed.
• LONG and SHORT batches run independently, i.e. it is possible that, at one moment, there is a running Batch for LONG interval but no running Batch for SHORT interval.

6.4.2.4 OBK Delta Messages Flow

The OBK Batching for LONG Batch interval is always turned on in the M7 system. It is applied to all users who connect via ComTrader as well as users who sent the Login Request with orderbookBatching parameter set to the value “LONG”.

The OBK Batching for SHORT Batch interval is available in the M7 system. It can be turned on when required and then it will be applied to all remaining users (= those users to whom LONG Batching does not apply).

The change of the Short OBK Batching configuration requires a failover of the M7 Core component in a rolling fashion.

6.4.2.5 Examples - SHORT and LONG Batching

The following examples show the SHORT and LONG OBK batching behaviour.

Please see below the legend that is shared across all examples.

Example 1 - Order added and removed within 1 SHORT Batch interval

Example 2 - Order added and removed in 2 SHORT Batch intervals

Example 3 - Order added and removed within 1 LONG Batch interval

Example 4 - Buy order and matching Sell order added within 1 SHORT Batch interval

Example 5 - PblcOrdrBooksReq is received - SHORT and LONG Batch interval immediately stop

Example 6 - SHORT and LONG Batch intervals run independently

6.4.3 PblcOrdrBooksReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: [All]
• Request Limits: 14/70

The Public Order Books Request is used to retrieve the local view of the public order books. It is possible to request the order book for a dedicated contract in a given delivery area or for all active contracts of a list of products. Either the contract and delivery area or the list of products must be defined in the request. A Public Order Book Request always returns a Public Order Books Response containing the complete information of the requested order books. M7 filters out orders from XBID for remote contracts that cannot be traded locally. Note that the purpose of the request is to get an initial state of the public order books. Subsequent updates of the public order books are sent using the Public Order Books Delta Report message, listing all modified orders. Client applications should process these delta reports to keep their view on the public order books up to date. Any Public Order Books Delta Report messages in which the order book revision numbers are smaller than those in the Public Order Books Request must be ignored.

The message flow is shown in the below figure:

6.4.4 PblcOrdrBooksResp

• Type: Inquiry Response
• Response to: PblcOrdrBooksReq (sent to private response queue).
• Broadcast: No
• Routing Keys: –
• Roles: [All]

The public order book is returned to the client as a result of a Public Order Books Request, and gives a complete overview of the requested public order book at the time of the request. In the case of remote products, M7 filters out orders using the messages that are broadcast by XBID for contracts that are not in-a trading phase according to the local schedule.

Subsequent changes to the public order books as a result of an order entry, modification, deletion or execution (including any order book relevant change received from XBID) are reported using a Public Order Books Delta Report. The Public Order Books Response and the Public Order Books Delta Report share the same Message Payload format.

The Public Order Books Response is sent to the private response queue of the requester.

6.4.5 PblcOrdrBooksDeltaRprt

• Type: Broadcast
• Response to: n/a
• Broadcast: Yes
• Routing Keys: [schema-version].prddlvr.[prodName].[dlvryAreaId] , [schema-version].prddlvr.[prodName].[dlvryAreaId].[routingKeySuffix] , [schema-version].prddlvr.batched.[prodName].[dlvryAreaId]
• Broadcast audience: All users with the assignment of a particular product and delivery area.
• Roles: [All]

The Public Order Books Delta Report is sent to the client as a result of any change in the order book as a result of an order entry, modification, deletion or execution or a change in cross border capacity. In the event that local trading for a remote product is closed, M7 does not forward the Public Order Books Delta Report received from XBID.

It contains a list of orders that have been added to the market, or changed as a result of the above mentioned actions. A quantity of 0 indicates that the order has to be removed from the order book.⁶

The behaviour of the message depends on which timer (contract expiry timer vs. delivery interval closure timer) runs first. In the event that the delivery interval closes before the contract has expired, a Public Order Books Delta Report will be sent for the delivery areas in which orders can no longer match, with the quantity of 0 indicating the order’s removal from these delivery areas. Once the contact expires, Public Order Books Delta Reports for these delivery areas with a quantity of 0 will not be re-distributed.

If the Orderbook batcher is enabled, Public Order Books Delta Reports will be sent without correlation-id in the AMQP Message Properties and the routing key will depend on the selected interval (SHORT or LONG). While for the LONG interval, the [schemaversion].prddlvr.batched.[prodName].[dlvryAreaId] routing key will be used, in case of the SHORT interval or when the Orderbook batcher is disabled, the routing key [schema-version].prddlvr.[prodName].[dlvryAreaId] will be used.

If the Orderbook batcher is enabled and Routing key split feature is enabled, then the [schema-version].prddlvr.[prodName].[dlvryAreaId].[routingKeySuffix] routing key will be used for SHORT interval. Routing key split can be enabled on environment level only. Routing key split is a performance improvement measure. It does not apply to environment(s) where Orderbook batcher is disabled. It does not apply to LONG interval where Orderbook batcher is enabled. Routing Key Suffix is a single digit number. Suffix is assigned to user during log in. Suffix is same value until log out. Suffix assigned might change with each login and as such it should be ignored.

The message layout is shared with the Public Order Books Response.

6.4.6 CashLmtReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: Trader, Market Operation, Broker, Market Maker, Clearing user
• Request Limits: 14/70

The Cash Limit Request is used to retrieve the current cash trading limit. The cash limit is used to limit the open financial risk position of a member. It is calculated on a member level and is valid for all traders belonging to that member.

The principal use of the Cash Limit Request is to obtain the cash limit at the start of a session, or after a communication breakdown. Subsequent changes to the cash limit are broadcast automatically by the backend.

The diagram below shows the typical message flow during a user session in respect of the Cash Limit Request and Cash Limit Report messages.

6.4.7 CashLmtRprt

• Type: Inquiry Response; Broadcast
• Response to: CashLmtReq (sent to the private response queue see Request-Response communication)
• Roles: Trader, Market Operation, Broker, Market Maker, Clearing user
• Broadcasted: Trader, Market Operation, Broker, Market Maker, Clearing user
• Broadcast Routing Keys: [schema-version].mbr.[mbrId]
• Broadcast Audience: All users from a particular member, Admins, Brokers with assigned members, Clearing users

The Cash Limit Report is provided in response to a Cash Limit Request or a broadcast that is a result of an event that changes the cash limit (Limit creation, modification, deletion or reset), as well as after the housekeeping of cash limits (deleting limits that were set up for past dates).

It is not sent during the order management requests (order entry, order execution). See the message flow diagram above (Cash Limit Request).

The message lists all of the cash limits of the desired Member, as well as the current cash limit with its revision.

When the Cash Limit Report is sent as a response, it is sent to the private response queue of the requesting user. All subsequent updates are sent as a broadcast so that all traders of the member are up to date.

6.4.8 CashLmtDeltaRprt

• Type:Broadcast
• Response to: –
• Roles: Trader, Market Operation, Broker, Market Maker, Clearing user
• Broadcast Routing Keys: [schema-version].mbr.[mbrId]
• Broadcast Audience: All users from a particular member, Admins, Brokers with assigned members, Clearing users

The Cash Limit Delta Report broadcasts the new current cash limit value in the event that the limit changed (e.g. order entry, order execution). All traders/brokers of the Member receive this message.

6.4.9 CommodityLmtReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: Trader, Market Operation, Broker, Market Maker
• Request Limits: 1/10

The Commodity Limit Request is used to retrieve the current commodity trading limits of a member. The commodity limit is used to prohibit short selling of a member. The commodity limit is product specific, not all products offer this feature. Please note that commodity limits are not relevant for intraday trading. It is calculated on a member level for every product and is valid for all traders belonging to that member.

The principal use of the Commodity Limit Request is to obtain the commodity limits at the start of a session or after a communication breakdown. Subsequent changes to the commodity limit are broadcast automatically by the back end. The only required parameter of the request is Member Id.

The typical message flow is shown in the below figure:

6.4.10 CommodityLmtRprt

• Type: Inquiry Response; Broadcast
• Response to: CommodityLmtReq (sent to the private response queue)
• Roles: Trader, Market Operation, Broker, Market Maker
• Broadcasted: Yes
• Broadcast Routing Keys: [schema-version].mbr.[mbr.Id]
• Broadcast Audience: All users from a particular member, Admins and Brokers with assigned members

The Commodity Limit Report is returned in response to a Commodity Limit Request, or a broadcast that is sent as a result of an event that changes the commodity limit (for products eligible for the commodity risk control functionality).

When the Commodity Limit Report is sent as a response it is sent to the private response queue of the requesting user. All updates are sent as a broadcast, so that all of the traders of the member are up-to-date.

6.4.11 MsgReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: All
• Request Limits: 14/70

This inquiry message is used to retrieve the public and/or private messages issued by the back-end system in the past.

The principal use of this request is to obtain a list of recent messages at login or after a communication breakdown between the client application and the backend. After the login, the client application will receive all messages (private and public) automatically as they are broadcast by the back-end.

It is necessary to define a period for which the messages are to be retrieved and to filter the message type by setting the appropriate value in the type field.

The message flow is shown in the below figure:

6.4.12 MsgRprt

• Type: Inquiry Response; Broadcast
• Response to: MsgReq (sent to private response queue)
• Roles: All
• Broadcasted: Yes
• Broadcast Routing Keys: [schema-version].prvt.bg.msg.[acctId],[schema-version].prd.[prodName], [schema-version].dlvr.[dlvryAreaId],[schema-version].mkt.[marketAreaId], [schema-version].mbr.[memberId], [schema-version].public
• Broadcast Audience: Depends on the particular message type

The Message Report is sent as a response to a Message Request to the private response queue of the requesting user, but it can also be broadcast without a prior request, for example

• when a user is logged out from an exchange;
• when a user is re-connecting after a connection loss;
• when an Admin is sending a text message to market participants
• when an order failed to be transferred during an automated order transfer (see DFS160a).

In case MsgRprt is response to MsgReq, the list of messages can be truncated given startDate and endDate exceeds the maximum number of messages configured in the application. In such a situation, refine startDate and endDate in MsgReq.

6.4.13 TradeCaptureReq

• Type: Inquiry Request
• Routing Keys: m7.request.inquiry
• Roles: Trader, Market Operation, Broker, Market Maker, Sales
• Request Limits: 56/280⁷

This message is used to retrieve trades created during the last x days, where x corresponds to the value of the attribute contractStoreTimeInDays in the SystemInfoResp:

• For Traders, a set of valid accounts must be specified and all private trades are returned. If no account is specified, or the request is sent with an invalid or non-existent account ID, an error response is returned.
• For a Market Operation user or Sales user the account is not needed (a given value will be ignored by the backend) and all trades in the system for the observation period are returned.

6.4.14 TradeCaptureRprt

• Type: Management Response, Broadcast
• Response to: TradeCaptureReq (sent to private response queue)
• Broadcasted: Yes
• Routing Keys: [schema-version].hlftrd.[acctId],[schema-version].trd.[mktAreaId]
• Broadcast audience: Half trade: Trader (owner of the order) and other traders from his Balancing groups, Broker with assignment to trader (owner of the order), Market maker (owner of the order) and other traders from his Balancing groups. Full trade: Admins, Sales, Settlement users, Clearing users
• Roles: Trader, Market Operation, Broker, Market Maker, Sales

The Trade Capture Report broadcasts private trade information as a result of the following actions:

• Order execution
• Trade cancellation
• Trade recall request
• Trade recall request processing

The broadcasts are sent to the traders assigned to the accounts for which the related orders were entered as well as to the market operations users. Trading participants will always receive half-trades, containing only the information of the order entered by that trading participant:

• If the trading participant entered a SELL order she will see only the SELL side of the trade.
• If the trading participant entered a BUY order she will see only the BUY side of the trade.

The Trade Capture Report is sent to the trading participants with the routing key [schema-version].hlftrd.[acctId]. Market Operation users will receive the complete trade information (both sell side and buy side). The Trade Capture Report is sent to Market Operation users with the routing key[schema-version].trd.[mktAreaId]. In the case of a local trade (between 2 delivery areas in the same market area) the message will be sent only once.

When the Trade Capture Report is sent as a reply to the Trade Capture Request, it will be sent to the private response queue of the requesting user (a trade or market operations user).

The Trade Capture Report contains at most the trades created during the last X days, even if trades for a longer or different period are requested in the Trade Capture Request. The number of days represented by X is set using the system parameter contractStoreTimeInDays.

The visibility rules of the data are the same for both the broadcast and response messages.