Skip to main content

"manageService"

Abstract

manageService configures the general settings of a FairCom Edge service.

The "manageService" action configures the general settings of a FairCom Edge service.

Things to know

  • "manageService" can also send standard actions to the engine to pause, resume, restart, shutdown, and startup the service.

  • A service either collects data and stores it in an integration table or it takes data in an integration table and delivers it to an external system.

Request examples

Minimal request example

{
    "api": "admin",
    "authToken": "anAuthorizationTokenFromTheServer ",
    "action": "manageService",
    "requestId": "00000012",
    "params": {
        "serviceName": "MODBUS"
    }
}
{
  "api": "admin",
  "authToken": "anAuthorizationTokenFromTheServer",
  "action": "manageService",
  "params": {
    "serviceName": "MODBUS",
    "authTokens": [
      "authToken1",
      "authToken2"
    ]
  }
}
{
  "api": "admin",
  "requestId": "3",
  "authToken": "anAuthorizationTokenFromTheServer",
  "api": "admin",
  "action": "manageService",
  "params": {
    "serviceName": "MODBUS",
    "authTokens": [
      "authToken1",
      "authToken2"
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "apiVersion": "1.0",
  "debug": "max"
}

Response examples

{
  "result": {
    "sessions": [
      {
        "authToken": "authToken",
        "username": "accountName",
        "description": "optional session description",
        "defaultOwnerName": "admin",
        "defaultDatabaseName": null,
        "defaultBinaryFormat": "hex",
        "defaultResponseOptions": {
          "binaryFormat": "base64",
          "dataFormat": "arrays",
          "numberFormat": "number"
        },
        "idleCursorTimeoutSeconds": 600,
        "idleConnectionTimeoutSeconds": 3600
      }
    ]
  },
  "errorCode": 0
}
{
  "requestId": "2",
  "result": {
  },
  "errorCode": -1,
  "errorMessage": "authToken invalid or expired.",
  "debugInfo": {
    "request": {
      "requestId": "2",
      "authToken": "anAuthorizationTokenFromTheServer",
      "api": "admin",
      "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"
    },
    "serverSuppliedValues": {
    },
    "errorData": {
    },
    "warnings": [
      {
        "warningCode": 0,
        "warningMessage": "",
        "warningData": {
        }
      }
    ],
    "executionPlan": {
    }
  }
}

"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)

"sessions"

contains session objects where each session minimally describes a session

array of objects



The "sessions" property is an array of session objects where each session object minimally describes a session.

Table 3. "sessions" property summaries

Property

Description

Type

Limits (inclusive)

"authToken"

signifies that the client is authenticated and authorized

signifies that the client is authenticated and authorized

string

Minimum length: 0
Maximum length: 255

"defaultBinayFormat"

defines the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client making it useful when the binary format is not specified in the action request

string

"base64"
"hex"
"utf8"

"defaultDatabaseName"

defines the default value of the "databaseName" property

string

Minimum length: 1
Maximum length: 64

"defaultResponseOptions"

defines a default value for "responseOptions" that is used by default in all other action calls

object

One of the following:

"numberFormat"
"dataFormat"
"binaryFormat"

"defaultOwnerName"

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

string

Minimum length: 0
Maximum length: 256

"description"

allows the client to describe an object for later identification

string

Minimum length: 0
Maximum length: 65,500

"hostname"

contains the name of the host device

string

"hostUuid"

contains the universal identifier of the server instance

string

"hostIpAddresses"

contains the IP addresses of the host

array of strings

"hostServerNamePort"

contains the server’s ISAM port or server name

string

"hostSQLPort"

contains the server’s SQL port

string

"idleConnectionTimeoutSeconds"

contains the number of seconds that a session with no activity will stay open

integer

0 - 2147483647

"idleCursorTimeoutSeconds"

contains the number of seconds to keep a cursor open

integer

0 - 2147483647

"sessionStartTimestamp"

contains the UTC date and time in ISO 8601 format of when the session was created

string

"sessionLastAccessedTimestamp"

contains the UTC date and time in ISO 8601 format of when the session last received a JSON Action message including the last time the session was pinged

string

"username"

contains the account name of a user or application

string

Minimum length: 1
Maximum length: 64