Skip to main content

"listServices"

Abstract

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.

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

"authTokens"

contains one or more authorization token strings

[]

array

At least one "authToken"



"result"

The "result" property is a required object set by the server that contains the result of an action.

Things to know:

Property summary

Table 2. "result" property summaries

Property

Description

Type

Limits (inclusive)

"apis"

describes and controls FairCom's jsonAction APIs

array of objects

"applicationRoot"

defines the base folder where FairCom's web applications are located

string

"applications"

describes and controls FairCom's app servers

array of objects

"defaultDatabaseName"

defines the default value of the "databaseName" property

string

Minimum length: 1
Maximum length: 64

"defaultOwnerName"

specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application

string

Minimum length: 1
Maximum length: 64

"integrationServices"

describes and controls FairCom's integration services

array of objects

"listeners"

describes and controls FairCom's listeners

array of objects



The "apis" property is an array of objects that describes and controls FairCom's jsonAction APIs. It defaults to an empty object.

Things to know:
  • 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.

Property summary

Table 3. "apis" property summaries

Property

Description

Type

Limits (inclusive)

"enabled"

enables or disables the service

Boolean

true
false

"serviceName"

contains a unique, descriptive name of the service

string



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/".

Things to know:
  • 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.

Things to know
  • An app server is a backend service that is used by one or more of FairCom's web applications. It listens to HTTP and/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/apps folder.

  • 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.

Property summary

Table 4. "applications" property summaries

Property

Description

Type

Limits (inclusive)

"enabled"

enables or disables the service

Boolean

true
false

"serviceLibrary"

contains the filename of the app server's dynamic link library

string

"serviceName"

contains a unique, descriptive name of the service

string

"uriPath"

specifies the endpoint where the app server listens for requests

string



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.

Things to know:
  • When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.

  • In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:

    • 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 Hub 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.

Things to know:
  • 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.

Property summary

Table 5. "integrationServices" property summaries

Property

Description

Type

Limits (inclusive)

"enabled"

enables or disables the service

Boolean

true
false

"serviceLibrary"

contains the filename of the app server's dynamic link library

string

"serviceName"

contains a unique, descriptive name of the service

string



The "listeners" property is an array of objects that describes and controls FairCom's listeners. It defaults to an empty array.

Things to know:
  • 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 HTTP and HTTPS protocols 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.

Property summary

Table 6. "listeners" property summaries

Property

Description

Type

Limits (inclusive)

"enabled"

enables or disables the service

Boolean

true
false

"description"

allows the client to describe an object for later identification

string

Minimum length: 0
Maximum length: 65,500

"port"

contains the port number

integer

"protocol"

contains the name of a protocol

string

"serviceLibrary"

contains the filename of the app server's dynamic link library

string

"serviceName"

contains a unique, descriptive name of the service

string

"tls"

contains optional properties for using TLS to create secure communications

{}

object