Running a Heartbeat Service in RiskShield

RiskShield is a fraud detection and prevention software, which is highly configurable on the server components. I got the desire to provide a stateless service, that any monitoring solution can poll and check if the RiskShield server is still available. Following configuration was done on Version 4.34a. The configuration options are provided by the manufacturer the Inform Software and described in their manual. It is an easy and straightforward example to demonstrate the configuration capability e.g. RiskShield Decision Server.

My solution is a http service that provides on a dedicated heartbeat port, a good response code (204 → no content) or json response with timestamp and an echoed message.

Server Configuration

The first step consists of declaring a HTTP server in the server.ini:

;Port = ${DecisionServerHeartbeatPort}
Port = 7799

As you can see, you can use a variable or hardcode it to a dedicated port. The Jetty HTTP Server will listen to port 7799.

Service Declaration

The Services section list all services of the RiskShield Decision Server. The Heartbeat service is named Heartbeat.

Heartbeat = HttpService(HeartbeatServer, /, Heartbeat)

HttpService is the service class, that needs further description. I chose the context root and no dedicated path, since I use a dedicated port for that. The last param is a project reference of the project.ini.

Format            = JSON
NoResponse        = false
Charset           = UTF-8
ResponseFormat    = JSON
TemplateFile      = ./heartbeat.json

Response Template

The request format is JSON. If a response is given, it shall be JSON encoded. I just create a simple template from scratch:

    "heartbeat": {
        "timestamp": ${HB_DATETIME},
        "message": ${echo}

As you can see, the template can reference a variable. More in the next section.

Project Configuration

The project.ini contains all projects regarding the processing. The Heartbeat project must be named like this:

Enable  = true
Project = Heartbeat
Plugins = SystemDateTime(HB_DATETIME)

The SystemDateTime Plugin will write the current timestamp into the variable HB_DATETIME.

Heartbeat in Action

Let’s get down to heartbeat :wink: . Start the Decision Server. It should give you in the Console Logging following messages:

SRV1001 | 15:35:00 | I | service 'Heartbeat [7799/]' started successfully

Poll with simple request

A simple request with curl or wget will just give you a 204 response code. In most cases, that is sufficient for a network load balancer.

[2016-11-10 15:31.52]  ~
[vinh.alpha] ➤ curl -v localhost:7799
* STATE: INIT => CONNECT handle 0x800705c8; line 1103 (connection #-5000)
* Rebuilt URL to: localhost:7799/
* Added connection 0. The cache now contains 1 members
*   Trying
* STATE: CONNECT => WAITCONNECT handle 0x800705c8; line 1156 (connection #0)
* Connected to localhost ( port 7799 (#0)
* STATE: WAITCONNECT => SENDPROTOCONNECT handle 0x800705c8; line 1253 (connection #0)
* STATE: SENDPROTOCONNECT => DO handle 0x800705c8; line 1271 (connection #0)
> GET / HTTP/1.1
> Host: localhost:7799
> User-Agent: curl/7.50.1
> Accept: */*
* STATE: DO => DO_DONE handle 0x800705c8; line 1350 (connection #0)
* STATE: DO_DONE => WAITPERFORM handle 0x800705c8; line 1477 (connection #0)
* STATE: WAITPERFORM => PERFORM handle 0x800705c8; line 1487 (connection #0)
* HTTP 1.1 or later with persistent connection, pipelining supported
< HTTP/1.1 204 No Content
< Date: Thu, 10 Nov 2016 14:35:14 GMT
* Server Jetty(9.2.18.v20160721) is not blacklisted
< Server: Jetty(9.2.18.v20160721)
* STATE: PERFORM => DONE handle 0x800705c8; line 1645 (connection #0)
* Curl_done
* Connection #0 to host localhost left intact
* Expire cleared

On The Decision Server Console you can see the established connection:

SRV1725 | 15:35:14 | I | [HeartbeatServer] new connection from /, now 1 connections
SRV1726 | 15:35:14 | I | [HeartbeatServer] close connection from /, now 0 connections

Semantical polling

As the Heartbeat Service is capable of a json response with a timestamp, you can measure the response time of your request. Furthermore you can send a message, that will be echoed in the response: Send a message with a json request.

curl -v localhost:7799 -d '{ "echo" : "vinh ist drin" }'

The outcome is this: riskshield-heartbeat