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 The
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 |
|
serviceName |
The See the The following services are available as of the V5 release:
|
Required - No default value | string | 1 to 64 bytes |