Engine Management Service API

Engine Management Service API

Summary 

This knowledgebase article provides information about Engine Management Service (EMS) API:
  1. frequently used API endpoints (applicable to all supported CE versions)
  2. procedure for enabling, capturing and viewing Swagger API documentation (valid starting with CE v16)

EMS frequently used API endpoints

Notes
Root-endpoint

https://<ems-address>:9727
  1. all of the following API endpoints are relative to this root.

Notes
Authorization

Basic authentication
  1. EMS username and password

Info
Determine active node in Engine cluster

GET /hbws/v1/serverlist
  • drill down in serverlist response for your server clusterName. Locate serverChain property and search for the node server identity having role: "ACTIVE". (Identity value may be PRIMARY, SECONDARY, TERTIARY)
  • sample response
    • {
      "gen": 1729084656072,
      "mgmtServerId": "lj-2k19-ems-4Z6CLQTV",
      "serverList": [
      {
      "groupType": "TERNARY",
      "isActivePartition": true,
      "lastError": {
      "id": "",
      "detail": ""
      },
      "hostOS": "WINDOWS",
      "serverChain": [
      {
      "server": "PRIMARY",
      "fileSystem": "SYNCHRONIZED",
      "registry": "SYNCHRONIZED",
      "role": "ACTIVE",
      [...]

InfoDetermine filesystem status (synchronized or not) in Engine cluster

GET /hbws/v1/serverlist

  • drill down in serverlist response for your server clusterName. Locate serverChain property and search for the property fileSystem. Should be "SYNCHRONIZED" for each node in serverChain.
  • sample response
    • {
      "gen": 1729084656072,
      "mgmtServerId": "lj-2k19-ems-4Z6CLQTV",
      "serverList": [
      {
      "groupType": "TERNARY",
      "isActivePartition": true,
      "lastError": {
      "id": "",
      "detail": ""
      },
      "hostOS": "WINDOWS",
      "serverChain": [
      {
      "server": "PRIMARY",
      "fileSystem": "SYNCHRONIZED",
      "registry": "SYNCHRONIZED",
      "role": "ACTIVE",
      [...]


Idea
Make Primary Active

POST /hbws/v2/server/<engine-server-name>/plan/makeactive
Request payload:
{
      "keepSync":true,
      "newActive":"PRIMARY"
}

Idea
Start Replication

POST /hbws/v2/server/<engine-server-name>/plan/startreplication
Request payload: (default, ensuring the apps are running)
{
      "startApplications":true
}

Idea
Stop Replication

POST /hbws/v2/server/<engine-server-name>/plan/stopreplication
Request payload: (default, with leaving applications running)
{
      "stopApplications": false
}

Idea
Start Applications

POST /hbws/v4/server/<engine-server-name>/applications/start
Request payload:
{}

Idea
Stop Applications

POST /hbws/v4/server/<engine-server-name>/applications/stop
Request payload
{}

Idea
Start Orphaned File Check

POST /hbws/v4/server/<engine-management-server>/data/orphanedfilescheck
Request payload:
  1. for checking orphan files on first passive (SECONDARY)
    1. {"server":"PRIMARY"}
  1. for checking orphan files on second passive (TERTIARY)
    1. {"server":"SECONDARY"}

Idea
Enable/Disable Inclusion File Filter

POST /hbws/v4/server/<engine-server-name>/filters/inclusion/edit
e.g. Following paylod disables System's plugin C:\PROGRAMDATA\NEVERFAIL-PROTECTED\** inclusion file filter: 
Recommendation: exercise this via EMS UI and check the API details for better understanding.

Request payload:
{
      "newPattern":"C:\\PROGRAMDATA\\NEVERFAIL-PROTECTED\\**",
      "enabled":false,
      "oldPattern":"C:\\PROGRAMDATA\\NEVERFAIL-PROTECTED\\**",
      "sponsor":"System"
}

Info
Get protected services

GET /hbws/v1/server/<engine-server-name>/services
  1. in response under services there are listed all the protected plus dependent services and their corresponding configuration.
    1. actualState - indicates service status on the mentioned node [Primary, Secondary, Tertiary]
    2. sponsors - indicates the name of the plugin(s) protecting the service
    3. e.g. in the below sample, lanmanserver: is protected, managed, monitored by FileServer plugin and running on Primary which is currently active server  
    4. "services": {           
            "PRIMARY": [
                  {
                      "originalStartupType": "Automatic",
                      "displayName": "Server",
                      "originalState": "Running",
                      "actualState": "Running",
                      "targetStateActive": "Restarted",
                      "onSecondFailure": "Heartbeat\\Recover Service",
                      "isManaged": true,
                      "onThirdFailure": "Heartbeat\\Recover Service",
                      "isProtected": true,
                      "useExtendedRecovery": false,
                      "sponsors": [
                          "FileServer"
                      ],
                      "name": "LANMANSERVER",
                      "targetStatePassive": "Running",
                      "isMonitored": true,
                      "onFirstFailure": "Heartbeat\\Recover Service",
                      "failureCount": 0
                  },
 

Procedure for enabling, capturing and viewing (Swagger) EMS API documentation

This procedure is valid starting with CE v16.

Starting configuration:

  1. By default, after CE installation, EMS API documentation is disabled.
  2. Initial APIs are empty only declarations, and in this form they are not interpreted/displayed in Swagger Editor. As the APIs get called, their properties (description, parameters, response codes, etc.) are captured in Swagger format.

Enable API documentation

  1. In  EMS registry, go HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Prefs\nfwebsvcs\management\nfmgtwebsvc and edit the value documentation_enabled = true
  2. Restart Neverfail Engine Management Web Services

Capture API definition

  1. using EMS UI, exercise the action/API you intend to document
  2. GET collected EMS API documentation*
    1. GET https://<ems-address>:9727/hbws//v6/server/localhost/documentation
      Response contains collected API documentation.
      This may be loaded to Swagger Editor for more user-friendly view.
      *not all APIs are collected. Contact Neverfail Support for guidance.

View API documentation in Swagger

  1. load collected API documentation in Swagger Editor. 

Applies to

Neverfail Continuity Engine Management Service v16 and beyond







    • Related Articles

    • How to enable HTTP Strict-Transport-Security (HSTS) in Continuity Engine Management Service

      Summary This Knowledgebase article provides information about how to enable HTTP Strict-Transport-Security (HSTS) in Continuity Engine Management Service The HTTP HSTS is a mechanism that allows websites to declare that they can be only accessed via ...

    • How to enable DEBUG level logging on Neverfail Continuity Engine Management Service

      Summary  This Knowledgebase article provides information about how to enable DEBUG level logging on Neverfail Continuity Engine Management Service. Procedure To enable DEBUG level logging on Neverfail Continuity Engine Management Service: On the ...

    • Check Continuity Engine Server Status

      This article describes how to check server status by reviewing several indicators, including the system tray icon, the Server Details page and Applications page in EMS, and Windows services. Check Server Status Learning objectives At the end of the ...

    • How to use the Engine Management Service

      Summary This Knowledgebase article provides information about using the Engine Management Service. More Information The Engine Management Service is used to control Neverfail software and provides access to the status of Neverfail Continuity Engine ...

    • Using the Neverfail Continuity Engine Management Service

      Summary This Knowledgebase article provides an introduction to the Neverfail Continuity Engine Management Service. More Information Using the Engine Management Service User Interface The Engine Management Service is the primary tool used for ...