Skip to main content

"alterCodePackage"

JSON ADMIN "alterCodePackage" action updates the code in the server

The "alterCodePackage" action updates the code in the server. Optionally provide a comment explaining the change.

Each time you alter the "code" or "codeFormat" properties, the server increments the version number of the code package and stores the previous version in the code package history. Each time you alter the other properties, the server updates them in place. It does not change the version number or write the change to the code package history.

Altering the "codeName", "comment", "description", and "metadata" properties has no effect on how the server runs the code package. Altering anything else affects how the server runs the code package.

You cannot alter the  "codeType" and "codeLanguage" properties.

To activate a code package, set the "codeStatus" property to "deprecated", "testing", or "active". This allows the server to start running processes that use the code package.

To deactivate a code package, set the "codeStatus" property to "developing", "deleted", or "inactive". This causes the server to finish running existing processes that use the code package, and prevents the server from running the code package again.

Tip

Immediately deactivate code that harms data to stop the server from running the code again.

Warning

WARNING: deactivating a code package prevents the server from running processes that rely on that code package. For example, deactivating a code package may break transform processes, triggers, and jobs.

Tip

To prevent disruptions to running code, clone an existing code package, give it a new name, improve the clone, remove the original from all active server processes, replace it with the new code package, and deactivate the old code package.

The server loads active code packages into instances of the language runtime. For example, the server runs multiple instances of the Google V8 JavaScript engine. When you alter the "code" property, the server finishes running the previous version of the code package without affecting the code the server is currently running. The next time the server runs the code package, it will use the new code.

Request examples

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
   "databaseName": "faircom",
    "ownerName": "admin",
    "codeName": "convertTemperature",
    "newCodeName": "convertTemperature new",
    "codeLanguage": "javascript",
    "codeType": "transform",
    "codeStatus": "active",
    "comment": "optional change comment",
    "description": "optional new description",
    "metadata": {},
    "code": "optional new code to replace old code",
    "codeFormat": "utf8"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "comment": "The new comment replaces the old comment."
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "active"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "testing"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName":"convertTemperature",
    "codeStatus": "deprecated"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "inactive"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "inactive"  
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "deleted"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "metadata": {"keyword":"temperature"}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "comment": "",
    "description": "",
    "metadata": {}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "comment": "New comment replaces old comment.",
    "description": "New description replaces old description.\nAnother description line.",
    "metadata": {"keyword":"temperature","favorites":true}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "newCodeName": "convertTemperature2",
    "comment": "Changed the name from convertTemperature to convertTemperature2.",
    "description": null,
    "metadata": null
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "1"
}
{
  "api": "admin",  
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "newCodeName": "convertTemperature2",
    "comment": "Modified the code",
    "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}"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Use the alterCodePackage API action to update stored JavaScript code in the server

API actionJSON ADMIN APIjsonActionalterCodePackagealterCodePackagesaltersCodePackagealtersCodePackagesalter code package
Table 1. Params property summaries

Property

Description

Default

Type

Limits (inclusive)

databaseName

specifies the name of the database

Defaults to the session's "defaultDatabaseName" property

string

ownerName

specifies the name of the owner

Defaults to the session's "defaultOwnerName" property

string

codeName

specifies the name of the code package

Required - No default value

string

newCodeName

when specified, the server renames the code package to the new name

null

string

codeLanguage

specifies the programming language of the code in the "code" property

Required - No default value

enum

"javascript"
"json"

codeType

specifies the type of code package

Required - No default value

enum

"transform"
"getRecordsTransform'

codeStatus

specifies the status of the code. The server only runs code with a status of "deprecated", "testing", or "active".

"developing"

enum

"developing"
"deleted"
"inactive"
"deprecated"
"testing"
"active"

description

describes the code package

""

string

metadata

contains user-defined properties that add keywords and tags about the code package

""

string

comment

describes the latest change to the code

""

string

codeFormat

specifies the encoding of the code in the code property

"utf8"

string

"utf8"

code

contains the source code stored in the server

""

Json string



"databaseName" is an optional string specifying the database name of the code package. It defaults to the session's "defaultDatabaseName" property when omitted or set to null. The package's unique identifier is the combination of "databaseName", "ownerName", and "codeName".

"ownerName" is an optional string specifying the account name that owns the code package. It defaults to the session's "defaultOwnerName" property when omitted or set to null. The package's unique identifier is the combination of "databaseName", "ownerName", and "codeName".

"codeName" is a required string containing the user-defined name for the code package. The package's unique identifier is the combination of "databaseName", "ownerName", and "codeName".

"newCodeName" is an optional string. When present, the server renames the code package from the current "codeName" to the "newCodeName". The server does not change the "codeName" when null or omitted.

"codeLanguage" is a required string. It is the programming language's name. Any string value is accepted. Currently, "javascript" and "json" are the only types of code the FairCom server can use.

"codeType" is the type of code package. Currently, the only allowed enumerated values include: "transform" and "getRecordsTransform".

"codeStatus" is optional and 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.

"description" is an optional string that describes the code package. The server indexes this field with a full-text index so that you can search for any word or phrase.

"metadata" contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages.

"comment" is an optional string explaining the code change.

"codeFormat" is an optional string that specifies the encoding of code in the code property. You must encode you 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.

"code" contains the source code. Before embedding it in a JSON string, encode the source code using the format specified in the "codeFormat" property.