This documentation is meant to be used by developers.

What is pixi Messaging?

Messaging enables software applications to connect and scale. Applications can connect to each other as components of a larger application or to user devices and data. Messaging is asynchronous, decoupling applications by separating sending and receiving data.

In pixi, messaging will be used for notifications near real-time multi-application scenarios and near real-time data exchange.

The message broker to support pixi MQ infrastructure is RabbitMQ. It uses the Advanced Message Queuing Protocol. Please read the basic concepts of this protocol here: AMQP concepts

Costs and Set-up

If your database is hosted by pixi, you don't need to pay anything additional to be able to work with pixi Messaging. If you are already using the pixi API, all costs are covered. In this case, pixi Messaging only needs to be activated, which is done by pixi Support.

Administrators can (de)activate events on their own: pixi Control Center - Messaging Events

If you have an in-house server and want to use pixi Messaging, please contact your account manager. Setting up pixi Messaging on your in-house server is a fee-based service, which needs to be done by pixi Support. In general, the messaging server hosted by pixi will be used, requiring for the outbound ports 5671 and 5672 to be open in your Firewall Settings.

Databases with version pixi 24.05 or higher must have the database setting Messaging - Web Management activated if you want to make administrative changes (disabled by default).

Terminology

Terms we will use throughout this document are the following:

Term	Description
pixi MQ	pixi MQ is the short form for "pixi Message Queuing" and defines the whole infrastructure of message brokers, vhosts, exchanges, users, shovels, specific sql and c# scripts and jobs, needed to achieve reliable messaging among different applications.
MQS	MQS is the short form of "Message Queue Server" or "Messaging Broker" installation. Possibly instead of MQS the term "Rabbit" or "RabbitMQ" will be used, which already implies the technology used for messaging broker.
localMQ or localMQS	LocalMQ/S is the RabbitMQ message broker installation on pixi database server.
cloudMQ or cloudMQS	CloudMQ/S is the hosted RabbitMQ instance in Amazon cloud, where all vhosts, exchanges and users with permissions are setup to support the main part of pixi*MQ infrastructure.
MQexchange	MQexchanges are Advanced Message Queuing Protocol (AMQP) entities where messages are sent. The exchanges take a message and route it into zero or more queues. The routing algorithm used, depends on the exchange type and rules called "bindings". In pixi MQ, exchanges on localMQ or cloudMQ will start with "pixiEX". So MQexchange for invoice created event will be named "pixiEXinvoiceCreated". Read about different exchange types in AMQP concepts. For pixi, currently important ones are fanout and topic.
Shovel	Shovel is a rabbitMQ plugin, which is used to reliably transfer messages from local MQexchanges to cloud MQexchanges. pixi MQ uses shovels to transfer messages from localMQ exchanges to cloudMQ exchanges, where they are possibly routed to underlying queues. More about shovels can be found here: Rabbit MQ - Shovel plugin
Queue	Queues are containers, that store messages to be consumed by applications. There can be many queues bound to the same MQexchange but consumed differently. Consuming of queues uses round-robin principle which means, that the message is removed after it has been consumed. This is useful, in case multiple apps use the same queue to share the load.
Consumer	Consumers are applications that subscribe to queues and then receive and process messages.
Producer	Producers are applications, that sends messages.

What is the Process behind?

Producers of events (notifications, messages), which can be the pixi database, pixi Web application or pixi apps, will post messages to one or more MQexchanges named pixiEX... (example pixiEXInvoiceCreated) on localMQ.
Messages from any MQexchange on localMQ will then as soon as possible be shovelled to MQexchange on cloudMQ.
In cloudMQ you then have to create a queue (also multiple queues are possible) and bind it to the proper MQexchange or more MQexchanges depending on the message type (topic or fanout).
You then need to configure your application(s) to listen to the queues, to process the information further.

Notes:
- If queues are not needed anymore, they have to be deleted manually or by consumers.
- The CLR (Common Language Runtime) and web service to post messages, are included on the producer side.

List of MQexchanges

For a complete list of all available MQexchanges and the content of messages, please check this article: List of MQexchanges.

Example Message

This is an example message of RequestPackageLabel event, which is sent to pixiEXRequestPackageLabel exchange. Messages are sent in JavaScript Object Notation (JSON) data format.

Note: Please consider for your implementation that the data array may (eventually) contain multiple records for various events combined in a single message, e.g. ItemStockChanged.

{
	"data":[
		{
			"invoiceKey": 361,
			"invoiceNr": "PIX0000003",
			"shippingAddress":{
				"company": "pixi* Software GmbH",
				"firstName": "John",
				"lastName": "Doe",
				"street": "Ivory Avenue",
				"houseNr": "1",
				"city": "Detroit",
				"zip": "12345",
				"state": "",
				"country": "GB", "eMail": "max.mustermann@email.com",
				"phone": ""
			},
			"shopAddress":{
				"name": "PIX",
				"address": "Walter-Gropius-Str. 15",
				"city": "Munich",
				"zip": "80807",
				"state": "",
				"country": "DE",
				"eMail": "pixi@pixi.eu",
				"phone": ""
			},
			"packageInformation":{
				"packageId": 14,
				"grossWeight": 1.8,
				"amount": 30.92,
				"currency": "EUR",
				"cashOnDelivery": 1
			},
			"shipVendor": "DPD"
		}
	]
}

How to connect

Connection Parameters

To connect to pixi Messaging server you can reuse SOAP API credentials:

Name	Example	Description
Messaging Server	mq.pixi.eu	Server you need to connect to
Virtual Host (VHost)	pixi_dem	"pixi_" + customers database name
Username	pixidem	Customers SOAP API username (without servername as prefix)
Password	********	Customers SOAP API password
Exchange Name	pixiEXOrderCreated	"pixiEX" + event name; see the list of MQ exchanges

Both, VHost and Username MUST only consist of small letters!

RabbitMQ Management

The RabbitMQ Management provides a graphical user interface for checking messages and channels as well as setting up exchanges and queues. Please note that you must enable the setting Messaging - Enable web management in Control Center, if you want to use the web interface.

Connectivity Test

After setting up a new queue, we recommend a first connectivity test. The following is an example command to fetch a named queue using the debian library amqp-tools. An example command line query could be this:

amqp-get --url='amqp://Username:Password@MessagingServer:5672/VHost' -q QueueName

Here's the example with parameter details:

amqp-get --url='amqp://pixidem:********@mq.pixi.eu:5672/pixi_dem' -q TestQueue

Binding Examples

Here are two examples of how to bind your application to exchanges using python and PHP.

Python

#!/usr/bin/env python
import pika

# use the same credidentials as for standard pixi* SOAP API
credentials = pika.credentials.PlainCredentials("pixidev", "pixidevpassword", erase_on_connect=True)

connection = pika.BlockingConnection(pika.ConnectionParameters(host='mq.pixi.eu',
virtual_host="pixi_dev",  credentials=credentials))
channel = connection.channel()

result = channel.queue_declare(exclusive=True)
queue_name = result.method.queue

channel.queue_bind(exchange='pixiEXInvoiceCreated', queue=queue_name)

print(' [*] Waiting for new invoices. To exit press CTRL+C')

def callback(ch, method, properties, body):
    print(" [x] %r" % body)
    # Add your actions here

channel.basic_consume(callback,
                      queue=queue_name,
                      no_ack=True)

channel.start_consuming()

You can find more information about how to bind to RabbitMQ exchanges using Python in this article: RabbitMQ - Python

PHP

This is a PHP example using AMQP library for PHP (amqplib).

<?php

require_once __DIR__ . '/vendor/autoload.php';
use PhpAmqpLib\Connection\AMQPStreamConnection;

$connection = new AMQPStreamConnection('mq.pixi.eu', 5672, 'pixidev', 'pixidevpassword','pixi_dev');
$channel = $connection->channel();

list($queue_name, ,) = $channel->queue_declare("", false, false, true, false);

$channel->queue_bind($queue_name, 'pixiEXInvoiceCreated');

echo ' [*] Waiting for new invoices. To exit press CTRL+C', "\n";

$callback = function($msg){
  echo ' [x] ', $msg->body, "\n";
  // Add your actions here
};

$channel->basic_consume($queue_name, '', false, true, false, false, $callback);

while(count($channel->callbacks)) {
    $channel->wait();
}

$channel->close();
$connection->close();

You can find more information about how to bind to RabbitMQ exchanges using PHP in this article: RabbitMQ - PHP

Advantages compared to "Pull" API

In this section there are some advantages listed, that pixi Messaging has compared to the "Pull" API approach.

Queues

Information, that are sent using pixi Messaging do not get lost. Messages "live" as long as they are consumed. So in case the target application is not reachable, it will consume the message, when it is back online. The message will wait, until it gets processed.

Push Messages

Information, such as customer / supplier order created, invoice created or invoice updated, will be actively pushed to a queue. Applications only need to subscribe to queues and then listen for new messages in order to be informed. So there is no need for the application to "ask" for changes made to orders or invoices because pixi Messaging provide this information automatically.

Scenarios

Shipcloud - Label Printing

Shipcloud is an external provider of shipping labels for a lot of different shipping vendors, e.g. DHL, DPD, UPS, GLS, etc.

In order to create a shipping label and post it back to pixi, the RequestPackageLabel message needs to be enabled to forward the needed information about a newly created invoice to shipcloud. A PDF shipping label is then created on shipcloud side and the URL to this label is sent back to the pixi database using pixi API.
In case of 1-Scan-Shipping™, it is even more important, that this part is done near real time because ship-out happens immediately after invoice creation.

Real Time Stock Export

Currently pixi exports stock to many different channels by different rules. This causes performance problems because of the workload, which is created when the server needs to post exported data to URLs and additionally the first channel might take a long time, so other ones have to wait and have stock out of sync for quite some time.

The solution to this would be two MQexchanges (notifications). One MQexchange could be of type "topic", where "topic" is the location ID where stock has changed. Everytime pixi would export data the old way and wait for the process to finish, it would then add a notification to this MQexchange, so that queues bound to this MQexchange can consume messages about stock changes in near real time.

Posting to MQexchange is really fast and does not influence database server in a way old export approach does. Since consumers (export channels like Afterbuy app, TB.One app or online shop) need the data about stock differently, we could introduce "topic" approach, so that the business logic of consumer applications can decide, which stock to read (location or summary based).

Another MQexchange could be created, which notifies about stock changes in batches (chunks), so that possible consumers don't always use webhooks to retrieve data from queues, but can start consuming the queue faster once they are notified by this webhook.