"listServices"
Return information about specified services
listServices returns information about each specified service.
The "listServices" action returns information about each specified service.
Note
The "listServices" action both lists and describes each service.
Things to know
When a valid
"authToken"property is present, this action returns all information about each service.When an
"authToken"is omitted, this action returns all information except for the"tls"property.
Request examples
Retrieve service information that does not require authorization request example
{
"api": "admin",
"action": "listServices",
"params": {}
}Retrieve extensive service information request example
{
"authToken": "replaceWithValidAuthtoken",
"api": "admin",
"action": "listServices",
"params": {}
}{
"authToken": "replaceWithValidAuthtoken",
"api": "admin",
"action": "listServices",
"params": {},
"requestId": "2",
"apiVersion": "1.0",
"debug": "max"
}
Note
FairCom Edge has more services than FairCom DB and the "jsonActionApiDefaults" property has different default settings.
{
"authToken": "replaceWithValidAuthtoken",
"result": {
"listeners": [
{
"serviceName": "http8080",
"description": "Port 8080 using insecure HTTP protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
"enabled": false,
"port": "8080",
"protocol": "http"
},
{
"serviceName": "https8443",
"description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
"enabled": true,
"port": "8443",
"protocol": "https",
"tls": {
"certificateFilename": "./web/fccert.pem"
}
},
{
"serviceName": "mqtt1883",
"description": "Port 1883 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this server",
"enabled": true,
"port": "1883",
"protocol": "mqtt"
},
{
"serviceName": "mqtts8883",
"description": "Port 8883 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this server",
"enabled": true,
"port": "8883",
"protocol": "mqtts",
"tls": {
"certificateFilename": "./web/fccert.pem"
}
},
{
"serviceName": "mqttws9001",
"description": "Port 9001 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
"enabled": true,
"port": "9001",
"protocol": "mqttws"
},
{
"serviceName": "mqttwss9002",
"description": "Port 9002 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
"enabled": true,
"port": "9002",
"protocol": "mqttwss",
"tls": {
"certificateFilename": "./web/fccert.pem"
}
},
{
"serviceName": "ISAM",
"enabled": false,
"port": "FAIRCOMS",
"protocol": "isam"
},
{
"serviceName": "SQL",
"enabled": false,
"port": "6597",
"protocol": "sql"
}
],
"jsonActionApiDefaults": {
"defaultApi": "hub",
"defaultBinaryFormat": "hex",
"defaultDatabaseName": "faircom",
"defaultDebug": "max",
"defaultOwnerName": "admin",
"defaultResponseOptions": {
"binaryFormat": "hex",
"dataFormat": "objects",
"numberFormat": "number"
},
"idleConnectionTimeoutSeconds": 3600,
"idleCursorTimeoutSeconds": 600
},
"applicationRoot": "./web/apps/",
"applications": [
{
"serviceName": "Ace Monitor",
"serviceLibrary": "ctmonitor.dll",
"enabled": true,
"uriPath": "AceMonitor"
},
{
"serviceName": "Data Explorer",
"serviceLibrary": "ctsqlexplorer.dll",
"enabled": true,
"uriPath": "SQLExplorer"
},
{
"serviceName": "ISAM Explorer",
"serviceLibrary": "ctisamexplorer.dll",
"enabled": true,
"uriPath": "ISAMExplorer"
},
{
"serviceName": "Rest CRUD",
"serviceLibrary": "ctrest.dll",
"enabled": true,
"uriPath": "ctree"
},
{
"serviceName": "api",
"enabled": true,
"uriPath": "api"
}
],
"apis": [
{
"serviceName": "hub",
"enabled": true
},
{
"serviceName": "mq",
"enabled": true
},
{
"serviceName": "db",
"enabled": true
}
],
"integrationServices": [
{
"serviceName": "opcua",
"serviceLibrary": "opcservice.dll",
"enabled": true
},
{
"serviceName": "modbus",
"serviceLibrary": "modbusservice.dll",
"enabled": true
}
],
"transformServices": [
{
"serviceName": "siemensUDT2JSON",
"serviceLibrary": "siemensudtservice.dll",
"enabled": false
}
],
"otherServices": [
{
"serviceName": "dbnotify",
"serviceLibrary": "./dbnotify/fcdbnotify.dll",
"enabled": false
},
{
"serviceName": "ctagent",
"serviceLibrary": "./agent/ctagent.dll",
"enabled": false
},
{
"serviceName": "thingworx",
"serviceLibrary": "./thingworx/ctthingworx.dll",
"enabled": false
},
{
"serviceName": "aggregation",
"serviceLibrary": "./aggregation/cttimestamp.dll",
"enabled": false
},
{
"serviceName": "cthttpd",
"serviceLibrary": "./web/cthttpd.dll",
"enabled": true
}
]
},
"requestId": "00000006",
"errorCode": 0,
"errorMessage": ""
}
{
"authToken": "invalidAuthtoken",
"debugInfo": {
"request": {
"authToken": "invalidAuthtoken",
"api": "admin",
"action": "listServices",
"params": {}
}
},
"errorCode": 12031,
"errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}
"params"
The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.
Properties summary
"params" properties summaryProperty | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
authTokens | contains one or more authorization token strings |
| array | At least one |
"result"
The "result" property is a required object set by the server that contains the result of an action.
It is a required part of the jsonAction specification standard.
Its properties vary with each action.
Properties summary
"result" properties summaryProperty | Description | Type | Limits (inclusive) | ||||
|---|---|---|---|---|---|---|---|
specifies and controls FairCom's jsonAction APIs | array of objects | ||||||
| enables or disables the service | Boolean |
| ||||
| specifies a unique, descriptive name of the service | string | |||||
specifies the base folder where FairCom's web applications are located | string | ||||||
specifies and controls FairCom's app servers | array of objects | ||||||
| enables or disables the service | Boolean |
| ||||
| specifies the filename of the app server's dynamic link library | string | |||||
| specifies a unique, descriptive name of the service | string | |||||
| specifies the endpoint where the app server listens for the requests | string | |||||
defaultDatabaseName | specifies the default value of the | string | 1 to 64 bytes | ||||
specifies the initial value of the | string | 1 to 64 bytes | |||||
specifies and controls FairCom's integration services | array of objects | ||||||
| enables or disables the service | Boolean |
| ||||
| specifies the filename of the app server's dynamic link library | string | |||||
| specifies a unique, descriptive name of the service | string | |||||
specifies and controls FairCom's listeners | array of objects | ||||||
| enables or disables the service | Boolean |
| ||||
| describes an object for later identification | string | 0 to 65,500 bytes | ||||
| specifies the port number | integer | |||||
| specifies the name of a protocol | string | |||||
| specifies the filename of the app server's dynamic link library | string | |||||
| specifies a unique, descriptive name of the service | string | |||||
| specifies optional properties for using TLS to create secure communications |
| object | ||||
| specifies an array of ciphers that the server will accept for communications with clients | string | |||||
| specifies the name and optional path of the certificate authorities certificate file (such as | string | |||||
| specifies the name and optional path of a server certificate file (such as | string | |||||
| specifies the name and optional path of a server key file (such as | string |
The "apis" property is an array of objects that describes and controls FairCom's jsonAction APIs. It defaults to an empty object.
Each API is a service provided by the FairCom server.
Do not change the settings of the object properties unless you disable an unused API.
The "applicationRoot" property is a string that defines the folder relative to the <faircomInstallation>/server folder (where FairCom's web applications are located on disk. Its default value is "./web/apps/".
The default value of
"./web/apps/"translates to the folder<faircom_installation>/server/web/apps.There is rarely a reason to change the
"applicationRoot".For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom.
The "applications" property is an array of objects that describes and controls FairCom's app servers. It defaults to an empty array which means no applications are configured to run.
An app server is a backend service that is used by one or more of FairCom's web applications. It listens to
HTTPand/or WebSocket requests and then returns results.An app server is not a web application. FairCom's web applications are single-page, browser-based applications that are served out of folders in the
<faircom_installation>/server/web/appsfolder.Each of FairCom's web applications call backend services from one or more app servers (contact FairCom for information on how to build and add your own app servers using C or C++).
Do not change the settings of the object properties unless disabling an unused app server.
The "defaultOwnerName" property is an optional string that is supplied at "createSession". It is used by the "ownerName" property which specifies the owner account name. It defaults to the "username". When "ownerName" is omitted, the server sets "ownerName" to the value of "defaultOwnerName". However, if "defaultOwnerName" is set to the empty string, then the "ownerName" is set to the empty string.
When
"ownerName"is omitted the server uses the"defaultOwnerName"property value set during login.In
"createSession"and"alterSession"when"defaultOwnerName"is omitted or set tonull:In the JSON DB API, the server sets
"defaultOwnerName"to the"username"of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.In the JSON Edge API and JSON MQ API, the server sets
"defaultOwnerName"to"admin"allowing the server to own the objects it creates.
Actions that create objects, such as
"createTable"and"createIntegrationTable", can omit the"ownerName"property making the server set"ownerName"to the value of"defaultOwnerName".When an action that creates an object sets the
"ownerName"property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.When
"ownerName"is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.
The "integrationServices" property is an array of objects that describes and controls FairCom's integration services. It defaults to an empty array.
An integration service is a connector that uses a protocol to collect information from devices and/or deliver information to devices — for example, FairCom Edge includes connectors that collect data from Modbus and OPC UA.
For information on how to build and add your own connectors using C or C++, contact FairCom.
Do not change the settings of the object properties unless disabling an unused connector.
The "listeners" property is an array of objects that describes and controls FairCom's listeners. It defaults to an empty array.
A listener is a service that listens on a specified TCP/IP port for a specified protocol.
FairCom servers provide listeners for the protocols:
"http""https""mqtt""mqtts""mqttws""mqttwss"
Each protocol is hardwired to a specific set of backend services:
The
HTTPandHTTPSprotocols are hardwired to support the jsonAction APIs and web applications.The MQTT and MQTTS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over TCP/IP.
The MQTTWS and MQTTWSS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over WebSocket.
For information on how to build and add your own listeners using C or C++, contact FairCom.
Do not change the object property settings unless disabling an unused listener.