Live Integration Notifications

In earlier versions of the integration framework, you could only extend the live integration by basically copying the code for the live integration project and building a custom live integration assembly from that. In other words, there were no real extensibility points, which made it difficult to e.g. reuse a project elsewhere or update the live integration down the road.

In contrast, Integration Framework v2 contains extensibility hooks which makes everything a bit easier such as notifications that can be subscribed to. This allows you to inspect and alter the data being sent to the remote system, and to handle connectivity issues.

The notifications for the live integration fall into three categories:

  • XML generation – these fire before and after the XML for a document or child element is rendered. This allows you to inspect an alter the data before it’s turned into XML, and to inspect and alter the final XML before it’s sent to the remote system. A typical use case for this is adding extra information to a request, e.g. data from a payment gateway.
  • Orders – these fire before and after a cart or order is sent to the remote system. This allows you to inspect an order and alter or cancel it being sent altogether. After the order is returned, you can then inspect the data returned.
  • ERP communication – these fire before and after the framework communicates with the remote system, and when exceptions occur

These are explained below - or browse the API documentation:

The notifications for XML generation all come in pairs of two – a Before and an After notification:

  • Before provides you with a reference to the object for which XML is about to be generated. This is your last chance to inspect and alter the object before it is converted to XML.
  • After provides you with a reference to the same object, as well as to the generated XML document or node. This is an excellent place to modify the generated XML or to append your own nodes.

Each notification exposes an associated Args class (that inherits NotificationArgs) which provides additional information about the object for which XML is being generated. The subscribers also expose a property called GeneratorSettings whose type inherits XmlGeneratorSettings.

The XMLGeneratorSettings base class exposes properties that determine which data is included in the XML and how it’s formatted. The properties are:

Property

Description

Beautify

A Boolean that determines whether or not to format the output XML with line breaks and indenting. Off by default for integration, but it’s turned on for the export XML options for orders and users, resulting in a more human-friendly format.

LiveIntegrationSubmitType

Defines the source of the submit to the ERP. Some options include LiveOrderOrCart (as part of the user interaction at the frontend), ScheduledTask (the XML was submitted from a scheduled task) and ManualSubmit (a user (re)submitted an order from the Dynamicweb backend. See the API documentation for all options.

This value serves mostly as a human-friendly identifier to see why a specific XML request was sent or created.

ReferenceName

A string indicating the nature of the request. Contains values like OrderPut or UserPut so can see the XML was created as part of a PUT / create request.

Child classes of XmlGeneratorSettings add additional properties that determine which data to include. For instance, the OrderXmlGeneratorSettings class includes the properties AddOrderFieldsToRequest and AddOrderLineFieldsToRequest to control whether or not to include order fields and order line fields.

The Live Integration Framework sends order XML to the remote system in several different situations:

  • When a user interacts with a cart in frontend
  • When an order is completed in frontend
  • When a backend user (re)submits an order to the remote system
  • When the scheduled task QueuedOrdersSyncScheduledTask submits an order to the remote system

In all of these cases, Dynamicweb fires the OnBeforeSendingOrderToErp and OnAfterSendingOrderToErp notifications. The Before notification is cancellable, so you can prevent the order from being submitted programmatically if required.

The integration framework communicates with the remote system at various times – such as:

  • When a cart is calculated
  • When an order is saved
  • When a request for live prices is made

By subscribing to these notifications, you can keep an eye on this communication and take some action whenever a connection is made, lost, or restored.

To put this all together, imagine the following example. In order to prioritize shipping, you like to send an indication on an order about the user’s group membership, When the user is a Gold Customer, you aim to ship the order the same day, before all other orders. To accomplish this, you can add a custom field to the order, that indicates whether the current user is a member of the group Gold Customers.

The IsGoldCustomer isn’t implemented in this example as it’s not relevant. What’s important about the sample code is how it subscribes OnAfterGenerateOrderXml, then uses the Order property of the OnAfterGenerateOrderXmlArgs class to find the ID of the user that placed the order and then uses the XmlDocument to find the order elements and finally appends a custom node with the group status:

C%23
using System; using System.Xml; using Dynamicweb.Ecommerce.LiveIntegration.Notifications; using Dynamicweb.Extensibility.Notifications; namespace Dynamicweb.Samples { [Subscribe(Order.OnAfterGenerateOrderXml)] public class AddInfoAboutGoldGroupMembershipToOrder : NotificationSubscriber { public override void OnNotify(string notification, NotificationArgs args) { var myArgs = (Order.OnAfterGenerateOrderXmlArgs)args; var document = myArgs?.Document; // Order can be found in tables/table[@tableName = "EcomOrders"]/item[@table = "EcomOrders"] var orderNode = document?.SelectSingleNode( "tables/table[@tableName = \"EcomOrders\"]/item[@table = \"EcomOrders\"]"); if (orderNode == null) { return; } var userId = myArgs.Order.CustomerAccessUserId; var isGoldMember = IsGoldMember(userId); AddChildXmlNode(orderNode, "isGoldMember", isGoldMember.ToString()); } private static void AddChildXmlNode(XmlNode parent, string nodeName, string nodeValue) { var node = parent.OwnerDocument.CreateElement("column"); node.SetAttribute("columnName", nodeName); node.SetAttribute("isCustomField", true.ToString()); node.InnerText = nodeValue; parent.AppendChild(node); } private bool IsGoldMember(int userId) { return true; } } }

If you this class into a Class Library and drop its assembly in your site’s bin folder, the next time that XML is generated for an order, it’ll contain a custom element for the group status:

XML
<column columnName="isGoldMember" isCustomField="True">True</column>

Note that because of the way XML is generated internally, this applies to all places where order XML is generated: for a cart, a real order, when the order is resubmitted from the backend or scheduled task and when you download a copy of the XML from within the backend of Dynamicweb.