describeCodePackages

Return information about specified code packages

The "describeCodePackages" action returns all the current information about the specified code package names including source code and package properties. 

Use "describeCodePackageHistory" to retrieve information about previous versions of a code package.

 

Request examples

Typical

{ 
  "api": "admin",
  "action": "describeCodePackages",
  "params": {
    "databaseName": "faircom",
    "ownerName": "admin",
    "codeNames": [ "convertTemperature" ],
    "codeFormat": "utf8 | base64 | hex | byteArray | json"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

List a code package

{ 
  "api": "admin",
  "action": "describeCodePackages",
  "params": {
      "codeNames": ["convertTemperature"]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Typical

{
  "result": {
    "data": [
      {
        "codeId": 4,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 2,
        "clonedCodeId": 0,
        "codeStatus": "deleted",
        "codeLanguage": "javascript",
        "codeType": "getRecordsTransform",
        "description": "New description replaces old description.\nAnother description line.",
        "metadata": {
          "keyword": "temperature",
          "favorites": true
        },
        "createdBy": "ADMIN",
        "createdOn": "2024-10-15T19:29:34.216",
        "updatedBy": "ADMIN",
        "updatedOn": "2024-10-15T19:56:49.879",
        "comment": "Modified the code and changed the name back",
        "codeFormat": "utf8",
        "code": "// The server runs this JavaScript code, which is registered in the server as a transform method.\nrecord.temperature_fahrenheit = record.source_payload.temperature\nrecord.temperature_celsius = getCelsiusFromFahrenheit(record.temperature_fahrenheit)\nrecord.temperature_status = calculateTemperatureStatus(record.temperature_fahrenheit)\n\nfunction getCelsiusFromFahrenheit(temperature_fahrenheit){\n    return (temperature_fahrenheit - 32) / 1.8;\n}\n\nfunction calculateTemperatureStatus(temperature_fahrenheit){\n    switch (true) {\n        case (temperature_fahrenheit < 0):\n            return \"alert: too cold\";\n        case (temperature_fahrenheit < 32):\n            return \"cold\";\n        case (temperature_fahrenheit > 80):\n            return \"hot\";\n        case (temperature_fahrenheit > 140):\n            return \"alert: too hot\";\n        default:\n            return \"normal\";\n    }\n}"
      }
    ]
  },
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "describeCodePackages",
      "params": {
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeNames": [
          "convertTemperature"
        ],
        "codeFormat": "utf8 | base64 | hex | byteArray | json"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

List a code package

{
  "result": {
    "data": [
      {
        "codeId": 4,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 2,
        "clonedCodeId": 0,
        "codeStatus": "deleted",
        "codeLanguage": "javascript",
        "codeType": "getRecordsTransform",
        "description": "New description replaces old description.\nAnother description line.",
        "metadata": {
          "keyword": "temperature",
          "favorites": true
        },
        "createdBy": "ADMIN",
        "createdOn": "2024-10-15T19:29:34.216",
        "updatedBy": "ADMIN",
        "updatedOn": "2024-10-15T19:56:49.879",
        "comment": "Modified the code and changed the name back",
        "codeFormat": "utf8",
        "code": "// The server runs this JavaScript code, which is registered in the server as a transform method.\nrecord.temperature_fahrenheit = record.source_payload.temperature\nrecord.temperature_celsius = getCelsiusFromFahrenheit(record.temperature_fahrenheit)\nrecord.temperature_status = calculateTemperatureStatus(record.temperature_fahrenheit)\n\nfunction getCelsiusFromFahrenheit(temperature_fahrenheit){\n    return (temperature_fahrenheit - 32) / 1.8;\n}\n\nfunction calculateTemperatureStatus(temperature_fahrenheit){\n    switch (true) {\n        case (temperature_fahrenheit < 0):\n            return \"alert: too cold\";\n        case (temperature_fahrenheit < 32):\n            return \"cold\";\n        case (temperature_fahrenheit > 80):\n            return \"hot\";\n        case (temperature_fahrenheit > 140):\n            return \"alert: too hot\";\n        default:\n            return \"normal\";\n    }\n}"
      }
    ]
  },
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "describeCodePackages",
      "params": {
        "codeNames": [
          "convertTemperature"
        ]
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params") 

Property Description Default Type Limits (inclusive)

codeFormat

 The "codeFormat" property specifies the encoding of code in the code property. You must encode your code to embed it in a JSON string. "codeFormat" currently only supports the "utf8" encoding, requiring you to use JSON rules to escape problem characters in your code with the \ backslash character, such as \n. Optional with default of "utf8" string "utf8"

codeNames

The "codeNames" property specifies the names of the code packages you want to be described.

  "params": {
    "codeNames": [
      "convertTemperature"
    ]
  },
 Required - No default value array of strings 1 or more strings

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. Your session's account must have the appropriate privileges to access the code package.

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

data

.clonedCodeId

The "clonedCodeId" indicates which copy the specified code package is out of all existing code package clones. If the specified code package is the original one, its value will be 0.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The cloned code ID.

data

.code

 The "code" property contains the source code. Before embedding it in a JSON string, encode the source code using the format specified in the "codeFormat" property. string 1 to 8,388,096 bytes

data

.codeFormat

 The "codeFormat" property specifies the encoding of code in the code property. You must encode your code to embed it in a JSON string. "codeFormat" currently only supports the "utf8" encoding, requiring you to use JSON rules to escape problem characters in your code with the \ backslash character, such as \n. string "utf8"

data

.codeId

 The "codeId" property specifies the unique numeric identifier of a code package. integer No limit

data

.codeLanguage

 The "codeLanguage" property specifies the programming language of the code contained in the "code" property . Any string value is accepted. Currently, "javascript" and "json" are the only types of code the FairCom server can use. string

"javascript"

"json"

data

.codeName

The "codeName" property contains the user-defined name for the code package.

It is an error to set "codeName" to the empty string "".

The package's unique identifier is the combination of "databaseName", "ownerName", and "codeName". See the "databaseName" and "ownerName" properties for more information.

 string 1 to 64 bytes

data

.codeStatus

 The "codeStatus" property specifies a new status for the code. When you create a code package, it defaults to "developing". When you alter a code package, it defaults to the current state. You may set it to one of the following states: "developing", "deleted", "inactive", "deprecated", "testing", or "active". You can use "alterCodePackage" to transition from any state to any other. See "Use "codeStatus" to make a package runnable". string

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

data

.codeType

The "codeType" property defines how and where a FairCom server can run the JavaScript code. See Code Package Types for how to use each type of Code Package. The following enumerated values are supported:

 string

"integrationTableTransform"

"getRecordsTransform"

data

.codeVersion

The "codeVersion" property indicates the version of the specified code package.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The version of the specified code package.

data

.comment

 The "comment" property explains the code change. string 1 to 65,535 bytes

data

.createdBy

The "createdBy" property indicates the name of the account used to create the specified code package.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 string The name of the account used to create the code package.

data

.createdOn

The "createdOn" property indicates the date and time the code package was created.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 timestamp The date and time when the code package was created.

data

.databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

data

.description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

 string 1 to 65,500 bytes

data

.metadata

The "metadata" field allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

data

.ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

data

.updatedBy

The "updatedBy" property indicates the name of the account last used to update the code package.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 string The name of the account last used to update the code package.

data

.updatedOn

The "updatedOn" property indicates the date and time the code package was last updated.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 timestamp The date and time the code package was last updated.
 

Was this article helpful?

Give feedback about this article

Related Articles