Skip to main content

System Event

Overview​

System Events are an Enactor upstream notification mechanism between different applications (e.g. between POS and EM) that Enactor platform supports to record specific events such as Device Startup or User SignOn. These Events can be created from any application and submitted to the System Event Queue for further processing at the Central Estate Manager. Alerting can be configured based on those system events.

What You Will Learn​

  • What a System Event is
  • How to create a System Event
  • Different Types of System Events
  • How to submit a system event
  • How to explore the System Event log
  • Generate an alert based on a System Event
  • Export System Events through Enactor Rest API

Instructions​

What is a System Event?​

System Events are small messages created on Enactor applications to record certain types of activities. Enactor uses this by default and the framework can be used to record custom system events. Each System Event carries a unique field Sequence Number which indicates the sequence id related to that event. Furthermore it contains the details below:

  • source application - Indicates the application type of the device which raised the event (e.g. POS, EstateManager, BackOffice)
  • topic - Indicates the category of the system event
  • event Date - Timestamp which the event was raised.
  • systemEventTypeId - Type of system event.(eg - SignOn, SignOff, Startup)

Here is a an XML example of a system event created when a user signs on an Enactor POS application.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:systemEvent xmlns:retail="http://www.enactor.com/retail">
    <retail:applicationId></retail:applicationId>
    <retail:transactionId></retail:transactionId>
    <retail:source>TLM_TST-DK0032-P5</retail:source>
    <retail:sourceApplication>POS</retail:sourceApplication>
    <retail:topic>Transactions</retail:topic>
    <retail:sequenceNumber>548</retail:sequenceNumber>
    <retail:transactionRecoveryId></retail:transactionRecoveryId>
    <retail:eventId>6ec7-:24fe441da81:05a225f3-:65796b74106f1a9a</retail:eventId>
    <retail:eventDate>2023-09-26T17:05:47.895+05:30</retail:eventDate>
    <retail:systemEventTypeId>SignOn</retail:systemEventTypeId>
    <retail:userId>TLM_MA</retail:userId>
    <retail:deviceId>TLM_TST-DK0032-P5</retail:deviceId>
    <retail:locationId>DK0032</retail:locationId>
    <retail:applicationVersion>2.7.644-SNAPSHOT</retail:applicationVersion>
    <retail:onlineUpdated>false</retail:onlineUpdated>
</retail:systemEvent>

How to create a System Event​

System Events can be created using the CreateSystemEventAction action

Create System Event Action

The following inputs are required

  • enactor.coreUI.ApplicationId - This should be set to "POS" if the System Event is created on a POS/PDP application.
  • enactor.mfc.Device - This should be set to the current Device. This can be done by mapping the device already present in the view.
  • enactor.mfc.SystemEventTypeName - This is a string representing the name of the system event. It will populate the systemEventTypeId field in the xml

Other inputs such as enactor.mfc.Location are optional but should be populated to ensure completeness of the system event. This is important if an alert needs to be configured at location level.

Different Types of System Events available​

The main java class for System Event is SystemEvent.java. This class can be extended to provide additional fields and Enactor already provides such additional system events, built for specific use case. Here are some examples:

  • DeviceStatusEvent - to record when a peripheral device is online or office
  • PasswordChangedEvent - to record when a user have changed their password on the POS
  • ReprintReceiptEvent - to record when a transaction receipt has been reprinted
  • StoreRecallEvent - to record when a transaction is being stored or recalled
  • UserChangedEvent - to record when a user is updated on the POS (e.g. a role is being added or removed)
  • FiscalSystemEvent - to record event related to fiscal (e.g. Tax configuration has been synchronised with the printer)

How to Submit the System Events to the queue​

System Events are submitted to the relevant queue by calling the Pos/Transaction/SendTransaction application process The queue name to use depends on the application from which it is created. That is configured in the process connection diagram. If a System Event is created at POS application, they will be submitted to local queue PosTransactions. Some specific events such as DeviceStatusEvents are written to separate queues.

POS Queue

Then those events are send to the ServerTransactions Queue at BackOffice side. Those events are visible in inbound documents of the Store Server.

Inbound Documents

Then those events are processed at BackOffice and written to the BackOfficeTransactionsOut queue. Those events are send to the TransactionsIn queue at Estate Manager side and after processing those events are written to SystemEvents Queue and SecondarySystemEvents Queue. EM System Events

info

Since all the queues are db backed file system queues, It is possible to inject System Event xml files to Estate Manager or BackOffice by simply copying them to the Queue folder in Enactor Home location.

  • Estate Manager - {EnactorApplicationHome}/Queues/TransactionsIn/in
  • Back Office - {EnactorApplicationHome}/Queues/BackOfficeTransactionsIn/in

The status of the above mentioned queues can be viewed through Queue Status Maintenance.

LogSystemEvent Application Process​

Simple System event can be submitted by simply calling the Pos/SystemEvent/LogSystemEvent application process. This will create a new system event, submit it to the System Event Queue from POS application. It is required to pass Device and SystemEventTypeName as process inputs.

How to explore the System Event log​

The processing of SystemEvents are handled by application process EstateDirector/Processing/ProcessSystemEvent At this time it is created a SystemEventLogEntry relevant to each System Event and saved in the Estate Manager database which then can be viewed at System Event Log Maintenance .

info

Please note that the System Event and the System Event Log Entry are two distinct entities. The Log Entry is a record of the System Event but does not contain all the information a System Event can have. The System Event Log is not to be used as a repository for the System Events.

System Event Log Maintenance

It is possible to identify which sort of activities have happen at a particular POS Device, Store or by a User by simply filtering by them. For instance

  • Compare Startup/SignOn/SignOff time of different POS devices by filtering from EventTypeID.
  • Investigate UnexpectedShutDowns of each POS device.

Generate an alert based on the system event​

It is possible to generate an alert based on a specific system event raised with respect to their occurrence in a configured time period. The notification mechanism can be configured to send an email or SMS to a specific user.

These alerts are generated by monitoring the System Event Log. This is configured at Alert Type Maintenance.

Alert Type Maintenance

For example, the example below shows the configuration to raise an alert if an UnexpectedShutdown event is raised from Back Office within 1 hour with a threshold limit of 5.

Configure Alert

System Events Export Rest API​

Enactor Rest API exposes an endpoint to export the System Events processed at Estate Manager which are written to SecondarySystemEvents using a rest service call.

POST {Enactor Rest API Base URL}/rest/systemEvents/export

Sample Request

{
  "fromDate": "2020-10-10T13:45:30",
  "toDate": "2020-10-15T13:45:30",
  "fileFormat": "XML",
  "compress": "true"
}

Sample Response

Response will send the byte stream of the zip file containing all the xml files(System Events) as per the given request.

Also the Secondary System Events count can be taken from

POST {Enactor Rest API Base URL}/rest/systemEvents/count

Sample Request

{
  "fromDate": "2020-10-10T13:45:30",
  "toDate": "2020-10-15T13:45:30"
}

Response Body

Response will contain the integer value respect to the system events count created between the given request parameters.

Exercises​

  • Create a System Event(new System Event Id) from POS side.
  • Submit it to the System Events Queue
  • Validate that the System Event is processed at both Back Office and Estate Manager
  • Validate the created System Event is visible at the System Event Log in Estate Manager.
  • Configure to trigger an alert based on the created new System Event.

Extensions​

Extends the SystemEvent.java java class to create your own system event

See Also​

  • How To Configure Alerts Monitoring How to Guide.