Adding an Item to the jPOS 'status' table

I had a good question posed to me the other day about the jPOS 'status' table: "How do you add items to it?"  I went back and read my other related posts and realized that I've sort of surrounded the point in the past, but had never directly addressed it.

First, take a look at this recent post about Solving Visibility Concerns with the jPOS UI.  There, I've posted a screenprint of what the 'System | Status' screen looks like, as rendered by our implemented jPOS-EE Web module.  That screen is simply painting a visual picture of the contents of the 'status' table from our jPOS application DB.  Our status table looks like this:

   id varchar(32) not null,
   name varchar(255) null,
   state varchar(8) null,
   detail varchar(255) null,
   groupName varchar(32) null,
   lastTick datetime null,
   timeout numeric(19,0) null,
   timeoutState varchar(8) null,
   expired tinyint null,
   maxEvents int null,
   command varchar(255) null,
   validCommands varchar (255) null,
   primary key (id)

On that 'System|Status' screen, you can click on any of the red/yellow/green status indicator lights to 'show' the details of that component.  You can see in the 'show' that we also display the items from our revision table that are related to this row id in the status table.

Then, by clicking on '[edit]' in that 'show' screen, you'll see that in our jPOS-EE Web UI, we give an administrative user the ability to update Name, Group, Timeout, 'On Timeout' and 'Max Events.'  The row id ('AMEX1' in this case) isn't something that can be altered, nor can you tweak the detail and 'last tick' columns.  Any changes made are reflected in our revision table.

To get a better feel for things, here's a snapshot taken of the contents of the 'status' table at one of our test sytems.  In terms of how jPOS keeps the current state and expired information updated, we have defined an '02_status_heartbeart.xml' element in our deploy directory that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<status-heartbeat class="org.jpos.ee.status.Heartbeat" logger="Q2">
<property name="interval" value="20000" /> 
<property name="status-id" value="heartbeat1" />
<property name="status-name" value="Heartbeat 01" />
<property name="status-group" value="00_System" />
<property name="status-timeout" value="30000" />
<property name="on-timeout" value="CRITICAL" />
</status-heartbeat>

In the jPOS framework, the status subsystem works in a passive way. Each status entry is 'touched' from the system component that controls it. Each component has an associated timeout. If a status entry has not been touched within the given timeout period, then somebody needs to move that entry from its current ‘OK’ status to the destination error condition (e.g., WARN, CRITICAL, OFF, etc.). When a jPOS-EE Web UI user hits the status page, we run that check on all entries; but if for some reason the users are not looking at that page, we need a way to check all statuses and move timed-out entries to the specified error condition. 02_status_heartbeat is in charge of that!

So, that leaves the question:  how do row entries get into 'status' table to begin with?  There are a couple of ways.  In the case of a QMUX Channel, for example, each channel has its own monitor element.  Let's continue with the 'AMEX1' example as I've described above.  We have defined in our system a corresponding monitor for that connection, as defined by an element in the deploy directory called 95_amex_monitor.xml.  It looks like this: 

<?xml version="1.0" encoding="UTF-8"?>

<channel-monitor name='amex0-monitor' class='org.jpos.ee.status.Monitor' logger='Q2'>
<monitor id="AMEX1 AMEX IPC 01" delay='10000' period='15000'>
<class>org.jpos.ee.ChannelMonitor</class>
<property name='channel' value='amex' />
</monitor>
</channel-monitor>

The first time that monitor successfully deploys, if there's not a row in the 'status' table with that ID ('AMEX1'), it gets created along with the starting name of 'AMEX IPC 01' (see bolded text).  [There's no magic to the name itself - just some customer-specific nomenclature to note that this is connection to what AMEX calls its IPC data center (in Phoenix) from our customer's '01' application node.]  Once that row is created, you can use the UI (as indicated above) to change the name, its group assignment, related timeout value and the timeout state.   Additionally, in the case of these channel monitors, we use a small SQL script to place the value 'START STOP' into the validCommands column of those rows (more on this feature in a subsequent post).  [Though we use a SQL script to do that (because it's only a one-time mod), you could also expose that column to the UI for update).]

Likewise, in our extract and reporting jobs, each one of them does a 'touchStatusManager' as the last step in any successful execution.  So, our AMEX extract (i.e., formatting a file of approved, non-reversed AMEX purchases per their specifications) contains a step that looks like this:

public void touchStatusManager () throws Exception {
statusManager.touch ("axextract AMEX Extract", Status.OK, fname);

Again, the same process holds true here - the first time the extract runs, it creates a new row in the status table (here, 'axextract') along with a starting 'name' value ('AMEX Extract').  Then, we go in (via the UI) after the first execution and assign the row to a group (so that the UI can provide nice groupings on it's display) and appropriate timeout values.  In the case of the extracts, at this client site they run every 24 hours, so we set up a timeout in production (those are the test values depicted in my earlier  example) equivalent to 28 hours, with a timeoutState of 'ERROR'.  In other words, if that AMEX Extract doesn't complete successfully at least once per every 28 hours, the operator monitoring that 'System|Status' screen is going to be confronted with a Red light on the indicator associated with 'AMEX Extract'.

So, now, hopefully you understand the mechanics and the process enough for me to quickly tell you that we can monitor Store and Forward ('SAF') queues via a SAF monitor.  For example, here's our 95-saf.xml.  It monitors our FDR queue:

<?xml version="1.0" encoding="UTF-8"?>
<saf-monitor class='org.jpos.ee.status.Monitor' logger='Q2'>
<monitor id="saf1 FDR SAF 01 Status" delay='10000' period='30000'>
<class>org.jpos.saf.SAFMonitor</class>
<property name='saf' value='saf' />
</monitor>
</saf-monitor>

So you know the the drill now (first time implemented establishes the row; then, you can modify ancillary info via the UI).