`"manageService"`

Configure settings for a FairCom Edge service

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

Typical request example

{
  "api": "admin",
  "authToken": "anAuthorizationTokenFromTheServer",
  "action": "manageService",
  "params": {
    "serviceName": "MODBUS",
    "authTokens": [
      "authToken1",
      "authToken2"
    ]
  }
}

Maximal request example

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

Successful response example

{
  "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
}

Failure response example

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

Properties summary

Table 1. "params" properties summary

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:

It is a required part of the jsonAction specification standard.
Its properties vary with each action.

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

sessions

contains session objects where each session minimally describes a session

array of objects

sessions

.authToken

specifies that the client is authenticated and authorized

string

0 to 255 bytes

sessions

.defaultBinaryFormat

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

sessions

.defaultDatabaseName

specifies the default value of the "databaseName" property

string

1 to 64 bytes

sessions

.defaultResponseOptions

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

object

"binaryFormat"

"dataFormat"

"numberFormat"

sessions

.defaultOwnerName

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

string

0 to 256 bytes

sessions

.description

describes an object for later identificaion

string

0 to 65,500 bytes

sessions

.hostname

specifies the name of the host device

string

sessions

.hostUuid

specifies the universal identifier of the server instance

string

sessions

.hostIpAddresses

specifies the IP addresses of the host

array of strings

sessions

.hostServerNamePort

specifies the server's ISAM port or server name

string

sessions

.hostSQLPort

specifies the server's SQL port

string

sessions

.idleConnectionTimeoutSeconds

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

integer

0 to 2147483647

sessions

.idleCursorTimeoutSeconds

specifies the number of seconds to keep a cursor open

integer

0 to 2147483647

sessions

.sessionStartTimestamp

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

string

sessions

.sessionLastAccessedTimestamp

specifies 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

sessions

.username

specifies the account name of a user or application

string

1 to 64 bytes

`"sessions"`

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