The PING service allows an ABL client to interrogate the state of a data service (online or offline) and the ABL application's ability to respond. It can be used in conjunction with other static service resources (such as /static/home.html), and the HTTP status to isolate whether the server, service, transport, and ABL application are available for use. Validating the state of data service or ABL application using the PING service is better than testing with static resources because the PING service runs ABL code.

The APSV, REST, and WEB transports use the ServerStatus() method of the OpenEdge.Rest.Admin.AppServerStatus class to implement the PING service. Each transport executes the same AppServerStatus class for the PING service, which can be extended to return application-specific information about database connections, PROPATH, loaded libraries, caches, available services, and more.

Note: The PING service is not available for the SOAP transport.

Transport Syntax

REST

GET { http | https }://{host}:{port}/[{web_app}/]rest/_oepingService/_oeping

WEB

GET { http | https }://{host}:{port}/[{web_app}/]web/_oepingService/_oeping
Note: Both the WEB and REST PING services can be tested using an HTTP client (such as an HTTP client application in ABL) or command-line utility such as curl, for example:
>curl -H "Accept: application/json" -X GET http://host:port/rest/_oepingService/_oeping
{"response":{"_retVal":""}}
>curl -H "Accept: application/json" -X GET http://host:port/web/_oepingService/_oeping
{"response":{"_retVal":""}}

Prior to OpenEdge 12.5, the PING service for the WEB transport could be enabled in one of two ways:

  • By configuring a handler in the openedge.properties file that associates the /_oepingService/_oeping endpoint with the OpenEdge.Web.PingWebHandler with the following line:
    handlern=OpenEdge.Web.PingWebHandler : /_oepingService/_oeping
    Note: handlern should be replaced with whichever sequential handler you are creating for _oeping. For example, handler1.
  • The other method of enabling the PING service for the WEB transport is to create an _oepingService directory at the following location within your PAS for OpenEdge web application directory structure: {instance-name}/webapps/{webapp-name}/WEB-INF/adapters/web/_oepingService/. In the _oepingService directory, create a file called _oepingService.handlers with the following content:
    {
	"version": "2.0",
	"serviceName": "_oepingService",
	"handlers": [{
		"uri": "/_oeping",
		"class": "OpenEdge.Web.PingWebHandler",
		"enabled": true
	}]
}
Note: When a GET method is invoked on /_oepingService/_oeping, the HandleGet method in the class that is configured in the web handler is invoked. The response body in HandleGet is displayed on the web page as output.

The PING service only responds to the URL as it is configured in openedge.properties or the _oepingService.handlers file.

You can configure the handler to be something other than =OpenEdge.Web.PingWebHandler: /_oeping /_oepingService/_oeping. For example, if the OpenEdge.Web.PingWebHandler is mapped to /ping, then a client must call instance/web-app/web/ping in order for the ServerStatus( ) =OpenEdge.Web.PingWebHandler: /_oeping method to be called.

OpenEdge 12.5 has added an ABL Service package for the WEB PING service that automates the deployment of the _oepingService.handlers file.

To deploy the PING service to the ABL application in OpenEdge 12.5+, run the following command:
>cd $CATALINA_BASE
>bin/tcman deployablsvc -oeds {DLC}/servers/pasoe/extras/oepingWebService.oeds -webapp {webapp-name} -ablapp {ablapp-name}
Note: If you are running in a Proenv shell, you can use the pasman command to deploy the PING service:
>pasman -i {instance-name} deployablsvc -oeds {DLC}/servers/pasoe/extras/oepingWebService.oeds -webapp {webapp-name} -ablapp {ablapp-name}

APSV

GET { http | https }://{host}:{port}/[{web_app}/]apsv/_oepingService/_oeping
In OpenEdge 12, the PING service for the APSV transport can be enabled in one of two ways:
  • Configure oepingEnabled=1 in the openedge.properties file.
  • Run OpenEdge/ApplicationServer/Util/apsv_oeping.p on happsrv (OUTPUT JSON_Data), where happsrv is the application server handle and JSON_Data is the JSON output.

JSON output format

When a PING is successful, it can return a JSON array with the following information:
{"response": {"_retVal":  "text" }}
Note:

No return to a PING indicates that the agent is available, since the default value for text is blank (" ").

To customize the return value, extract the OpenEdge.Rest.Admin.AppServerStatus class from the oe-install-dir/src/OpenEdge.ServerAdmin.pl procedure library and place the customized version in your PROPATH.

If a PING is not successful, it returns a JSON array with the following information:

{"_errors": [ {"_errorMsg": "error_text",
        "_errorNum": error_number} ]}

Note that the error message may include additional properties,

Securing the PING service

You can restrict access to the PING service in the /web-app/WEB-INF/oeablSecurity.csv file. For example, to restrict everyone from accessing REST or WEB PING, add the line in bold: 

############## Intercept-url definitions for the REST transport URIs###############
"/rest/_oepingService/_oeping",”*”,"denyAll()" 
"/rest/**","*","hasAnyRole('ROLE_PSCAdmin')" 
    ###################################

############## Intercept-url definitions for the WEB transport URIs###############
"/web/_oepingService/_oeping",”*”,"denyAll()" 
"/web/**","*","hasAnyRole('ROLE_PSCAdmin')" 
    ###################################
Note: Order is important. The line with denyAll(), which restricts access to PING, must appear before the following line, which allows access to all REST services.

Create a custom WEB and REST transport PING service

To alter the behavior for both the WEB and REST transport ping services, the easiest approach is to create a new AppServerStatus class in a directory structure of OpenEdge/Rest/Admin/ within your PROPATH, ahead of any default DLC paths.

For example:
  1. Start by creating the following directory structure within your {instance-name}/openedge directory: 
    >cd {instance-name}/openedge
>mkdir OpenEdge/Rest/Admin
    Note: using {instance-name}/openedge as the basis for the class exploits the fact that this directory is automatically included in your PROPATH.
  2. Create an AppServerStatus.cls file inside of the Admin directory with the following contents:
    block-level on error undo, throw.

class OpenEdge.Rest.Admin.AppServerStatus: 

    method public character ServerStatus ( ):
        return "Pong!".
    end method.
        
end class.
  3. Restart the PAS for OpenEdge instance or terminate any existing agent PIDs.
    A test of the WEB and REST ping services should then result in the following:
    >curl -H "Accept: application/json" -X GET http://host:port/rest/_oepingService/_oeping
{"response":{"_retVal":"Pong!"}}
>curl -H "Accept: application/json" -X GET http://host:port/web/_oepingService/_oeping
{"response":{"_retVal":"Pong!"}}

This simple example can be illustrative for porting existing WEB classes to use the handler syntax with PAS for OpenEdge.