External Notifications

There are currently two types of notifications.

1. Periodic/Scheduled notifications

2. Instant/Immediate notifications

The following sections describe how each of these types are handled and as a result should affect how you react to the notifications.

Scheduled notifications

A scheduled notification is one where a current state can be reported at any given time using some simple rules. Scheduled notifications are triggered by the job scheduling system, at the intervals configured in the system, like any other scheduled job. It is important to note that most (if not all) scheduled notifications can include the same messages multiple times. For instance if a notification is scheduled to be run once every hour, the same message could end up being sent 24 times during 1 day (and more still depending on how the daily maintenance routines are).

Immediate notifications

An immediate notification is one that happens as a result of some process. Often this process is an InfoSystemss user who presses a button, menu or as a side effect of doing some other concrete action in the system. Often (not always) immediate notifications cannot be re-run because the state that they notify about is lost after it has occurred. It is possible for a notification type to be both immediate and scheduled; this depends on the nature of the event not all events can be both types and not all events are practical to have as both types.

Configuration of the listeners is done via the administrative application interface. Configuration consists fo two things, global configuration values and a schedule for when notifications should be run.

Each notification type is associated with a configuration option. This option is a list of URLs that notifications will be sent to when they are triggered. The URLs are built by the external system according to the development specifications and are, as such, not decided by Infosoft.

If a notification is configured with more than one URL, a notification will be sent to each URL in the list. If one or more of the configured listeners are offline or in an error state, when notified they will not be notified again and the notification will be lost for that particular listener. This is of note mostly for immediate notification types since most scheduled notifications are sent multiple times and can be caught at a later point in time.

Scheduled notifications will appear in bulks, i.e. lots of small messages for all the changes in the given period. Notifications will arrive for all titles, so if you are only interested in one title you have to filter away titles you don't need.

Once you have developed a listener, you have to contact the the people managing the InfoSystems installation and have them add your URL to the notification type you want.

First of, before you start developing one or more listeners, please read the subscription introduction includes an overall introduction to how the system works.

All notifications requests are implemented as simple HTTP requests posting content the same way an ordinary HTML form would do it. That is a post request using form URL encoded data.

In terms of implementation details this means that for each endpoint/url a page should accept url encoded POST data in the format described by the notification type.

No response code is required as no status is updated in the InfoSystems database, but to avoid unnecessary issues with timeouts, logging and so forth we prefer that a HTTP Status Code 200 OK is returned when the request has been received/handled.

Notes to Implementers
Consider handling immediate requests asynchronously; alternatively reduce handling time to a few milliseconds as there will be cases when a system user will be waiting in the other end.

This section presents a list of the notifications available and describes the intended function of these. Note that the notifications can be used for things that they were not intended for.

Notification: CustomerNumberChanged

This notification is used to inform about a change in customer number.

Trigger Conditions (Immediate)

An order is imported into the system and an existing duplicate is found. Thus the number that was assigned at the time of the order is no longer valid.

Parameters

Notification: SubscriptionChanged

This notification is used to inform about a change in a subscription that either signifies a start-up, or a change in the active subscription such as a product change, a term change or something similar. Stops and temporary stops are not a part of these messages.

Trigger Conditions (Scheduled)

This notification is triggered if a change is going to occur between the previous and the next distribution dates. For instance, if a subscription starts at the next distribution date, a notification will be sent including the new product and term. Please note that these messages will be sent for all new deliveries, even though the deliveries are the same as the previous deliveries.

Parameters

Notification: SubscriptionStopped

This notification is used to inform about a stop in a subscription that either signifies a complete cancelation or a temporary pause period.

Trigger Conditions (Scheduled)

This notification is triggered if a stop is going to occur between the previous and the next distribution dates. For instance, if a subscription stops at the next distribution date, a notification will be sent for the customer and title.

Trigger Conditions (Immediate)

The SubscriptionStopped notification also occurs when a new subscription order is forcefully cancelled by a user. This often happens if an order was placed containing invalid data, or to prevent fraud.

Parameters

Note that in the case where SubscriptionStopped is used to cancel an order, the changeDate will be the current time of the cancellation. The rest of the details will be of the order, and not an actual subscription.

Notification: OrderHandled

This notification is used to inform about attempts at handling subscription orders.

Trigger Conditions (Immediate)

Currently the OrderHandled event is fired when an order has been handled automatically by the auto-import routines and when an order is imported manually. This event will be fired even if an import fails, any subsequent manual handling is outside the managed scope and will need manual processing in external systems.

Parameters

The following tries to cover a few common issues and questions that are often asked.

• Time progression (or how distribution dates works)
• Scheduled messages arrive multiple times, is something wrong?
• We keep getting messages with old data (change dates)
• Messages arrive for all titles
• How do we Debug/Test these notifications

Time progression (or how distribution dates works)

The entire subscription system operates on a time concept where everything is centered around a publications distribution. Simply put, dates does not progress at midnight each day, instead it progresses when someone pushes a button to indicate the deadline for new registrations have passed. At that time, the next distribution date is moved, from whatever it is currently to the next entry in the publication calendar. Often this new date is tomorrow, but if a publication has a weekly or even monthly frequency, then the new date is one week or one month ahead in time.

Scheduled messages arrive multiple times, is something wrong?

As described above scheduled messages are typically an indication of what happens between two distribution dates. If notifications are configured to be sent multiple times within two distribution dates, a message will be sent multiple times because the change is valid within the timespan that is being analyzed when the scheduled notifications are to be sent.

There might be several reason for a specifc schedule, typically its a question of wanting to react on registrations carried out offline in a relatively fast manner. For publications with a low distribution frequency, for instance once a month, it could be suitable to just schedule notification to be sent once a week or even once a month. Infosoft can help you decide, but ultimately it comes down to the business requirements.

In any event, this is by design and the listener must handle repeated messages in some way.

We keep getting messages with old data (change dates)

The most common reason is that someone exported the production database to a test environment and forgot to remove the listener configuration. In which case your listener is now receiving data from the production and the test system.

Another common reason for this is simply that a publication/title has been stopped and maintenance is not being done for that publication any longer.

The solution is simply to ignore messages for that title, or better yet have someone archive the title and its data to a different database and remove it from the production system.

Messages arrive for all titles

Messages arrives for all titles, the notification system is not configured on a title by title basis as some events relate to customer entities. The listener just have to ignore titles it is not interessted in.

How do we Debug/Test these notifications

First of: refer to the section about troubleshooting and logging for how to enable general logging.

It is possible to enable logging on the scheduler and wait for another round of messages to be sent. This is the recommended approach if you want to know what is being sent in a production environment.

The recommended approach for testing is to install Fiddler (or a similar HTTP sniffer) and on the administrative client do a manual execution of the event type you need to test. If you are unable to install Fiddler, the administrative client can be configured to log messages just the same as the scheduler.

As you might have noticed the notifications system is rather primitive. It is not a fully fledged Publish-Subscribe solution nor is it a great externally exposed Event Sourcing mechanism.

There is no way to acknoweldge that a message has been received (or failed), and no way for the notification mechanism to filter messages already sent. Thus each listener should be able to deal with the fact that some messages might arrive often!

The main reasoning so far has been to keep the system simple in order to reducethe likelyhood for errors, and there are usually more effective ways of achieving the same thing that the event system does. The secondary reasoning being that doing it properly would require expensive architectural changes with no real benefits.

Other Resources