`"listSessions"` (JSON Action)

Return a list of active sessions

The "listSessions" action returns a list of active sessions that the logged-in account is authorized to see. The list can be filtered to include sessions from specific usernames.

Links: Concepts | Tutorials | FAQs

Request examples

Minimal

{
  "api": "admin",
  "action": "listSessions",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "requestId": "2",
  "api": "admin",
  "action": "listSessions",
  "params": {
    "usernameFilter": [
      "jim"
    ]
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Success

{
    "result": {
        "sessions": [
            {
                "username": "ADMIN",
                "description": "optional user description of session for troubleshooting",
                "authToken": "replaceWithAuthTokenFromCreateSession"
            }
        ]
    },
    "requestId": "00000045",
    "errorCode": 0,
    "errorMessage": "",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Failure

{
  "authToken": "invalidAuthtoken",
  "requestId": "2",
  "debugInfo": {
    "request": {
      "authToken": "invalidAuthtoken",
      "api": "admin",
      "action": "listSessions",
      "requestId": "2"
    }
  },
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}

The "listSessions" action returns a list of active sessions that the logged-in account is authorized to see. The list can be filtered to include sessions from specific usernames.

API actions

JSON ADMIN API

JSON Action

admin session

listSession

listSessions

listsSession

listsSessions

list session

return session information

check logged in sessions

filter user sessions

active sessions

view session information

access session information

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.

Properties summary

Table 1. "params" property summaries

Property	Description	Default	Type	Limits (inclusive)
usernameFilter	(optional) contains strings of usernames of accounts in order to filter a list of sessions	`[]`	array	1 to 64 bytes

`"result"`

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

Essential information:

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

session

.authtoken

signifies that the client is authenticated and authorized

string

0 to 225 bytes

session

.defaultBinaryFormat

(optional) specifies the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client when the binary format is not specified in the action request

string

One of the following: "base64", "hex", or "byteArray".

session

.defaultDatabaseName

(optional) specifies the default value of the "databaseName" property

string

1 to 64 bytes

session

.defaultResponseOptions

(optional) specifies a default value for "responseOptions" that is used by default in all other action calls. "includeFields" and "excludeFields" are mutually exclusive and "includePaths" and "excludePaths" are mutually exclusive

object

session

.defaultOwnerName

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

string

0 to 256 bytes

session

.description

(optional) specifies an object for later identification

string

0 to 65,500 bytes

session

.hostname

specifies the name of the host device

string

session

.hostUuid

specifies the universal identifier of the server instance

string

session

.hostIpAddresses

specifies the IP addresses of the host

array of strings

session

.hostServerNamePort

specifies the server's ISAM port or server name

string

session

.hostSQLPort

contains the server's SQL port

string

session

.idleConnectionTimeoutSeconds

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

integer

0 to 2147483647

session

.idleCursorTimeoutSeconds

(optional) specifies the number of seconds to keep a cursor open

integer

0 to 2147483647

session

.sessionStartTimestamp

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

string

session

.sessionLastAccessedTimestamp

specifies the UTC date and time (in ISO 8601 format) when the session last received a JSON Action message, including the last time the session was pinged

string

session

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

`"defaultBinaryFormat"`

The "binaryFormat" property designates how binary values are formatted in the JSON request and JSON response message. Beginning in version 13.0.4, FairCom changed the default value for "binaryFormat" from "base64" to "hex". You can maintain backward compatibility by changing the "defaultBinaryFormat" property to "base64" in the <faircom>/config/services.json file.

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , and "result".
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

"listSessions" (JSON Action)

Return a list of active sessions

Request examples

Minimal

Maximal

Response examples

Success

Failure

The "listSessions" action returns a list of active sessions that the logged-in account is authorized to see. The list can be filtered to include sessions from specific usernames.

API actions

JSON ADMIN API

JSON Action

admin session

listSession

listSessions

listsSession

listsSessions

list session

return session information

check logged in sessions

filter user sessions

active sessions

view session information

access session information

"params"

Properties summary

"result"

Properties summary

"sessions"

"defaultBinaryFormat"

Note

Note

`"listSessions"` (JSON Action)

`"params"`

`"result"`

`"sessions"`

`"defaultBinaryFormat"`