Skip to main content

Notifications

The Notifications system integrated into our solution allows to alert an external system of different events occurring in the application, for example a single customer database or document management. Retail operations users can therefore subscribe their integrated solutions to events that may interest them, in order to update them.

A Notification is characterized by several types of information:

  • Its triggering type: Synchronous or Asynchronous
  • The entity concerned: Contact, Document, ...
  • The type of event that occurred on the entity in question: Search, Detail, Validation, ...

Notification types​

Two types of notifications are managed by the system: synchronous and asynchronous.

Synchronous notifications / WebPlugins ​

The system triggers an immediate notification by calling a specified url, and waits for a response from the solution that subscribed to it, possibly allowing the display of feedback messages to the end user.

warning

Only one External system can be subscribed to a given Synchronous notification.

Some specific sync notifications may allow you to choose between 2 different calling modes: API and iFrame.

API mode​

This is the default calling mode. The specified URL is directly called like if part of the Retail Ops API. No new page is displayed here.

iFrame mode​

Only available for some specific sync notifications. The specified URL is loaded into a new iFrame, allowing the External system to display a user interface for its integration. A set of parameters related with the notification entity context is added to the iFrame URL in order for the External system to get all required information for an eventual Retail Ops API call.

Asynchronous notifications / Webhooks & Deltas ​

The notification is triggered independently from the Retail operations application, via a notification queue system. It is not immediate: please notice that a delay (few minutes) may exist between the moment when Retail Ops triggers an async notification and the moment when it is processed by the system.

Webhooks​

The list of async notifications is processed periodically by a dedicated system, which calls the specified urls without expecting any specific response. This allows one or more External systems to be automatically notified. No possible feedback from the subscribed solutions is displayed to the end user here.

info

Several external systems can be subscribed to a given Asynchronous notification.

Deltas​

Instead of being automatically called, an external system can also decide to periodically query our API by itself in order to get these notifications, via the Delta notifications methods.
The Deltas API is directly linked with the Webhooks solution, since they both allow to process the exact same list of async notifications. But the Deltas solution allows an External system to eventually retrieve "missed" notifications (for example if the provided url was not available for a given period and could not be successfully called by the Webhooks system).

note

Please note that the async notifications are stored in the delta queue for a maximum of 15 days. After this delay, they are automatically removed from the list.

Entities concerned​

Several Retail operations entities are likely to trigger notifications:

  • Contacts: several notifications can be triggered from Retail operations Customers:
    • Search : it is possible to query an external system to search for a Customer, rather than the Retail operations database.
    • Details : when loading the details of a Retail operations Customer, it is possible to ask an external system to return the updated information.
    • Validation : when entering/modifying a Customer from Retail operations, it is possible to alert an external system in order to pass it the information entered.
  • Documents: notifications can be triggered on Retail operations Documents, depending on their Document Level (Quote, Order, Order after measurement, etc.):
    • Validation : only when the Manual Document Validation system is activated (use of the "Modify" and "Save" buttons). Alerts an external system of the new entry/modification of the Document, if it has changed since the last notification possibly triggered.
    • Cancellation : when a Document is cancelled, a Webhook notification can also alert an external system.
    • Pricing : allows the ability to call an External system in order to correct the prices of a list of products, depending on their catalog and store.
    • Payment + : allows the ability to call an External system in order to validate a payment on the Document.
  • Project Workflow: notifications can be triggered anytime a Retail operations Workflow changes for a Project:
    • Validation : anytime a Project workflow evolves (i.e. moves one step forward in the project progress flow), a Webhook notification can alert an external system.
    • Cancellation : when a Project workflow transition is cancelled, a Webhook notification can also alert an external system.
info

The list of entities and event types that may trigger notifications is subject to change.

Subscription settings​

Several types of information are required in order to correctly configure your notification subscriptions:

  • Your entry point Url to be called by the triggered notification, and eventually a required API Key used to call it.
  • The notification object type:
    • Contact
    • Document
    • Workflow
    • ...
  • The type of event who triggers the notification:
    • Search
    • Details
    • Validation
    • Cancellation
    • Pricing
    • ...
  • For some specific objects (such as Documents), the entity type:
    • Quote
    • Order
    • Delivery
    • ...

Please refer the "Subscribing to Notifications" page for more information about how to link your system to Retail Ops notifications.

Standard call format​

All notification calls and responses will follow a standard base format.

Call:

{
  "eventType": "objectType.eventType",
  "entityTypeID": long,  // Type Identifier of the relevant object
  "entityID": long,      // Identifier of the object
  "data": object | array // Detail of the event depending on the event.
}

Response:

{
  "success": boolean,
  "message": string,
  "errorLevel": int,
  "errorCode": string,
  "data": object | array // Detail response to the event, depending on the event.
}

Error levels​

Below are the supported values for the errorLevel field:

ValueCodeDescription / Behavior
0OKDefault value for a success result. No message displayed.
10NOTIFICATIONAllows RetailOps to display the message content in a brief notification box (even in case of a success).
20INFORMATIONAllows RetailOps to display the message content in an Information dialog box (even in case of a success).
30WARNINGAllows RetailOps to display the message content in a Warning dialog box (even in case of a success).
40ERRORDefault value for a failure result. RetailOps will display the message content in an Error dialog box.
50CRITICALUnsupported failure result. RetailOps will display the message content in an Error dialog box.

Error codes​

The errorCode field is a simple string that can be used by any external system in order to inform the end-user of some specific types of errors. We advise you to prefix the error codes triggered by your own system with a known "keyword" that will help you identify them and make them unique.
Below are some of the values that may be automatically returned by the Retail Ops system and which may explain why a Notification could not be properly triggered:

Error CodeDescription
NOTIFICATION_ENTITY_NOT_FOUNDThe requested Retail Ops entity (Contact, Document, etc.) could not be found (e.g. wrong or obsolete ID, insufficient access rights, etc.).
NOTIFICATION_NO_INTERNAL_CODEThe requested Retail Ops entity is missing an Internal code.

Status codes​

If the statusCode field, when responding from the external system, returns something other than the code 200 ('OK'), we will consider it as a critical level error.

Swagger example​

On your swagger interface, the ExternalNotificationTest category groups a set of examples of how to implement notification entry points. You can find a quick overview of these methods in the Notifications Sample methods API section.