manageService

Configure settings for a FairCom Edge service

The "manageService" action sends a command to a FairCom server service to pause, resume, restart, shut down or start up that service.

It acts on these kinds of services: 

  • JSON APIs: hub, mq, db, and integration.
  • Web applications: Ace Monitor, Data Explorer, and ISAM Explorer.
  • HTTP and HTTPS listeners such as http8080 and https8443.
  • Other services that are enabled in services.json, such as datachangestream.

It doesn’t support MQTT listeners, connector services such as opcua or modbus, transform services or code services. Each returns error 12006 and other services that are disabled return error 1141.

Use "listServices" to find service names. Each entry in "listeners", "applications", "apis", "integrationServices", "transformServices", "codeServices", and "otherServices" has a "serviceName". Service names are case-sensitive and must be used exactly as "listServices" returns it. Some entries can’t be managed and return error 100: ISAM and SQL listeners, the "api" application and the "cthttpd" service.

 

Request examples

Pausing a service

This command pauses a service. A paused service stays loaded in memory but stops acting on requests.

  • Paused JSON API answers every request with HTTP 503.
  • Paused web application answers its URL with HTTP 503.
  • A paused listener refuses new connections on its port. Connections that were already open keep being served until the client closes them.
  • A paused other service, such as datachangestream, is stopped and actions that use it fail until it is resumed.
{
  "action": "manageService",
  "params": {
    "serviceName": "hub",
    "command": "pause"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": ""
}
 
 

Resuming a service

This command resumes a paused service.

{
  "action": "manageService",
  "params": {
    "serviceName": "hub",
    "command": "resume"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": ""
}
 
 

Restarting a service

This command shuts down and restarts a service. Don’t use it on an HTTP listener, it will fail with error 1100 and leave the listener shut down until you start it back up.

{
  "action": "manageService",
  "params": {
    "serviceName": "integration",
    "command": "restart"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": ""
}
 
 

Shutting down a service

This command shuts down a service. It stops answering until it starts up again. A listener that is shut down refuses new connections, but connections that were already open keep being served. 

Note If you shut down the HTTP and HTTPS listeners, you will not be able to run JSON actions to restart them. You must restart the server itself.

{
  "action": "manageService",
  "params": {
    "serviceName": "http8080",
    "command": "shutdown"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": ""
}
 
 

Starting up a service

This command starts up a service that has been shut down.

{
  "action": "manageService",
  "params": {
    "serviceName": "http8080",
    "command": "startup"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": ""
}
 
 

 

Response examples

Success

{
    "authToken": "replaceWithAuthTokenFromCreateSession",
    "debugInfo": {
        "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "action": "manageService",
            "params": {
                "serviceName": "modbus",
                "command": "pause"
            },
            "responseOptions": {},
            "debug": "max"
        }
    },
    "errorCode": 0,
    "errorMessage": ""
}
 
 

Failure

{
  "requestId": "2",
  "result": {
  },
  "errorCode": -1,
  "errorMessage": "authToken invalid or expired.",
  "debugInfo": {
    "request": {
      "requestId": "2",
      "action": "manageService",
      "params": {
        "authTokens": [
          "an AuthToken to be described"
        ]
      },
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string",
        "includeFields": [
        ],
        "excludeFields": [
        ],
        "includePaths": [
        ],
        "excludePaths": [
        ]
      },
      "apiVersion": "1.0",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
    },
    "errorData": {
    },
    "warnings": [
      {
        "warningCode": 0,
        "warningMessage": "",
        "warningData": {
        }
      }
    ],
    "executionPlan": {
    }
  }
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

command

The "command" property controls the standard behavior of a service. Commands are not case-sensitive. When omitted, the action returns error 12010 "Not able to find required parameter property [command]". Any value other than those below also returns error 12010 "invalid command".

The "command" property can be set to any of the following:

  • "pause" stops a service from acting on requests while it stays loaded. 
  • "resume" resumes a paused service.
  • "restart" shuts down a service and restarts it. 
  • "shutdown" shuts down a service.
  • "startup" starts up a service that has been shut down. 

For a listener, a command that doesn't fit its current state returns error 1100: pausing or shutting down a listener that isn't active, or resuming or starting one that is already active. A JSON API, web application or other service returns 0 for the same commands. 

Required - No default value string enum 

"pause"

"resume"

"restart"

"shutdown"

"startup"

serviceName

The "serviceName" property contains the name of a FairCom input or output service. 

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

Required - No default value string 1 to 64 bytes