The notification service allows to register a search query and get notified whenever documents matching the search query are being inserted, updated or deleted. As currently implemented the notification service is intended to support the synchronization of content between our backend server systems. The notification service is not capable of sending emails.

How to use the notification service?

Get in contact with the ContentHub team (_HL_Panama@haufe-lexware.com). They will help you with the search query and make sure that the proper application scopes do exist.

1. (If not yet done) create yourself an account in this portal
2. (If not yet done) register your application
   1. remember to leave the checkbox for OAuth2.0 Flows unchecked
   2. in case you are using a Server side application, make sure to select "Confidential: Server side application" from the Client Type dropdown
3. Subscribe your application to the notification service by clicking on the "Subscribe" button at the end of this page
   1. please leave the checkbox "Trust this application" unchecked
   2. choose the trial or unlimited plan depending on your needs
   3. inform the ContentHub-team that your subscription is created, they will assign the application scopes to it. (Only after the application scopes are assigned the notification service will create any notification events, because without scopes your search query will not hit any documents at all.)

Getting started

Your Endpoint

The first you need to set up is an HTTP-Server which can handle POST-requests. The URL to your HTTP-Server and your request handler must be static. Your server and the request-URL is called endpoint.

Authentication can be done with shared secrets that are send in the HTTP-Headers.

When your endpoint is running, you can start to create a notification subscription. Creating a notification-subscription is done with a notification-creation-request:

{
  "query": "application:portals documentType:News Arbeitsschutz",
  "email": "peter.sullivan@haufe-lexware.com",
  "allowedDelay": "PT10M",
  "messageType": "POST",
  "messageFormat": "JSONv1",
  "endpoint": "https://my.endpoint.haufe.io/news-on-arbeitsschutz",
  "connectionTimeout": "PT10S",
  "headers": [ {
    "name": "my-secret",
    "value": "123"
  } ]
}

• email the email address where you want to be alerted if the endpoint you provided for receiving notifications is not reachable.
• allowedDelay is a Duration PT10M means a period with time 10 minutes.
• messageType POST is the only supported messageType currently.
• messageFormat JSONv1 is the only implemented format currently.
• connectionTimeout of your endpoint: again a Duration-String; if your endpoint and network between ContentHub and your endpoint is fast and performant 10 seconds should be plenty, if your endpoint or the network has high latency or low bandwidth then pick 30 seconds or more.
• headers allows you to specify multiple headers, that ContentHub will send to your endpoint; this can be used for authentification with a shared secret.

Supported Concepts

General

For every notification-subscription we register the given notification-query in our database. Whenever documents are being inserted, updated or deleted our database will trigger an alert, if a notification query matches this document. We use the alerts to write a change-event onto a message queue. A scheduler will poll from the message queue and create a POST-message in the wanted messageFormat. The polling rate is determined by the allowedDelay.

Suspensions

Each notification-subscription can be suspended. A suspension is always defined by setting a timestamp for the end of the suspension-period. As long as a notifiaction-subscription is suspended:

• no messages will be send by ContentHub to your endpoint
• all change-events remain on the message queue, thus when the end of the suspension-period is reached ContentHub will start to create change-messages for all of them (no change events will be lost during a suspension-period)

Suspensions are designed to releave your endpoint from back-pressure. If you know in advance that you will have a service-outage you can suspend your notifiaction-subscription on your own. Also if ContentHub recognizes your endpoint as unresponsive it will start to suspend your notification-subscription for successively longer and longer periods. At the end of suspension-period ContentHub will try to send a message to your endpoint. If your endpoint is responsive again the suspension is ended and ContentHub will try to send messages at the regular pace.

Queries like in search

The queries can be used in the same way as is in the search-service. But as we do not need highlighting, sorting or scoring of the search results, there is no support for weighting terms or boost expressions.

View Swagger definition »