ITAS Events Services

Hivedome have created an Eventing Messaging Service which will enable our clients to interact with events that happen inside ITAS. Interaction with Events are via Web Services.

The basic idea is for Client applications to register a ‘mailbox’ with ITAS and then poll the mailbox for new events. ITAS will publish those events to the mailbox as they happen.

Event Service FAQs

Q1. Are the events in real time? Yes, as soon as they happen in ITAS, a message is sent to any mailbox that is registered for that event type. Clients can set up a ‘Long Poll’ so they receive notification as soon as the even happens rather than at the point of making their request.

Q2. Are the events sent in the correct order? Yes, all events are published to the eventing system in the order they happen. If event order is important to you then do not multi-thread polls (requests) to your mailbox. Ordered delivery is only guaranteed for single threaded, single polling applications.

Q3. Can events be guaranteed delivery? Yes, once a client receives notification that an event has happened, it needs to be read. Only when the reader (application) has confirmed the event will it be removed from the queue.

Q4. What type of events are published? Operational notifications are triggered from within ITAS Apps and cover a wide-range of activities. Data Change alerts are self-configurable and can be setup to trigger on Insert and Update activity.

Q5. What happens to events that are not read? Events that are not read, or rather confirmed as read stay in the queue until they have been confirmed as ready. To prevent a huge backlog of events building up mailboxes not subscribed to will time out after 10 day and all messages removed.

Eventing Web Services Call Order Explained

Here is the order of the essential messaging services:

	Service	Input Parameters	Response Fields	Status
1	Events/Register	subscriber name(your choice/reference no.)	SubscriberID	You are now a registered Subscriber.
2	Events/Subscribe	subscriber ID from above, Comp code(AA), topic(INVOICES)	Null*	You now have a mailbox set up.
3	Events/Peek	subscriberId, timeout period **	Message count, Next message ID. ***	You now have the message ID.
4	Events/Receive	subscriberid, messageid, locktimeout	Message Body	You now have your message.
5	Events/Confirm	subscriberid, messageid, lockid	Messgage Id	Your message has now been removed from the queue.

Notes:

* Please note that even null responses receive a Response Code. The code sent for a correct web service call is 200, any other response code requires investigation. For a full list of response codes please see this page Link .

** A time out period can be sent by the caller. The default period is 90 seconds and this cannot be exceeded. We recommend setting a time out period of around 60 seconds.

*** If no messages are available when the request is made and no messages become available before the timeout period is reached, a timeout response will be sent. At this point a new ‘Peek’ request should be made by the client. It is this cycle of Peek, timeout, peek, timeout, peek, message, peek that ensures events are received in real time.

Long Polling Sequence Diagram

The diagram below gives a visual representation of the services needed to be called in order to set up a mailbox, Peek messages and Pop them from the queue.

Other Event Services

Events\ViewSubscriptions – return a list of active mailboxes for the given subscriber ID

Events\Unsubscribe – deletes a mailbox. It is important that this step is undertaken when messages are no longer wanted, failure to do so will result in a backlog of messages.

Events\ViewTopics – returns a list of available topics.

Events\Publish – for future use, not currently active. Enables the publication of events to the message Queue.