Real-Time Synchronization for a Connector: How Webhooks and Push Notifications Are Used

In this topic, you can find information about the process of real-time synchronization through a connector between MYOB Acumatica and an external system.

Processing of Commerce Webhooks

When an administrator starts real-time synchronization on the Entities (BC202000) form by clicking Start Real-Time Sync on the form toolbar, the system calls the IConnector.StartWebhook method. The system uses this method to initialize the webhook scopes in the external system. Each webhook scope is a situation when the webhook, such as a customer update, is sent. The webhook scopes are specified in the Webhooks parameter of the BCProcessorRealtime attribute of the processor.

When an external system sends a webhook request, MYOB Acumatica uses the webhook handler class to receive the webhook request and to place the message in a queue in the queue broker (which is RabbitMQ by default). The queue has the commerceQueue prefix. You can monitor the status of this queue on the System Queue Monitor (SM302010) form. The messages are then processed as described in the Real-Time Synchronization section of this topic.

For BigCommerce, Shopify, or other compatible systems, the webhook handler class is the BCWebHookHandler internal class. The class expects the following data in the query:

  • type: The connector type
  • company: The company ID in MYOB Acumatica
  • validation: The hash code that is generated by MYOB Acumatica, which indicates that the message is expected

For BigCommerce webhooks, the class expects this data in headers. For Shopify webhooks, the class expects this data in the URL parameters.

If you cannot configure the external system to send webhook requests in one of these formats, you can implement a custom webhook handler class.

When the administrator stops real-time synchronization on the Entities form by clicking Stop Real-Time Sync on the form toolbar, the system calls the IConnector.StopWebhook method.

Processing of Commerce Push Notifications

For real-time export, MYOB Acumatica includes a number of predefined generic inquiries that define the data changes for which MYOB Acumatica should send notifications to the MYOB Acumatica Commerce Framework. These generic inquiries are listed on the Generic Inquiries tab of the Push Notifications (SM302000) form for the Commerce notification destination, which is predefined in the system. The names of these generic inquiries begin with the BC-PUSH prefix.

You can create custom generic inquiries for the monitoring of entities that are not included in the predefined inquiries. You can then create a custom notification destination of the Commerce Push Destination type on the Push Notifications form. In the list of inquiries for this notification destination, you include both the custom generic inquires and the needed predefined generic inquiries.

For a data query that is defined by a predefined or custom generic inquiry, when the system identifies a change in the results, the system generates a notification and adds it to a queue in the queue broker, which is RabbitMQ by default. This queue has the primaryQueue prefix and is used for all push notifications generated by MYOB Acumatica.

An MYOB Acumatica background thread processes the notifications from this queue and sends the commerce notifications to the notification destinations of the Commerce Push Destination type. By default, the system includes only one notification destination of the Commerce Push Destination type, which is the Commerce notification destination. The Commerce Push Destination type is defined in the PX.Commerce.Core.Model.Notification.BCPushNotificationDestination class, which implements the PX.PushNotifications.NotificationSenders.IPushNotificationSender interface.

The notification destination of the Commerce Push Destination type processes the commerce notifications and places them in another queue in the queue broker (which is RabbitMQ by default). The queue has the commerceQueue prefix, and you can monitor its status on the System Queue Monitor (SM302010) form. The messages are then processed as described in the next section.

Real-Time Synchronization

The commerce background thread processes the commerce notifications from the queue with the commerceQueue prefix. To improve the performance of the commerce connector, this thread works with a 20-second delay. That is, when the thread receives a message, it waits for 20 seconds before it starts to process this message. For example, if a user has saved a customer record three times in the last 15 seconds, the system generates three push notifications about the changes. Because the second and third modification all happened within the 20-second delay of the first push notification, the commerce connector synchronizes only the version of the customer record from the most recent push notification.

The commerce background thread updates the BCSyncStatus database table with the information about the modified record. You can view the data from this table on the Sync History (BC301000) form. Depending on the option selected in the Real-Time Mode box on the Entities (BC202000) form, the commerce background thread does one of the following:

The processing of import and export notifications is implemented with the IConnector.ProcessHook() and IConnector.ProcessPush() methods, respectively; the methods’ default implementations are available in PX.Commerce.Core.BCConnectorBase<TConnector>. These default implementations call the IProcessor.ProcessHook() and IProcessor.ProcessPush() methods, respectively, which are implemented in PX.Commerce.Core.BCProcessorBase<>.

If any error occurs during the preparation or processing of the data for synchronization, the error is displayed on the System Events tab of the System Monitor (SM201530) form.