"alterCodePackage"
JSON ADMIN "alterCodePackage" action updates the code in the server
The "alterCodePackage" action updates a package's code and optional metadata. The server finishes running existing instances of the code and automatically uses the new code when it runs new instances. Altering the code is useful for immediately rolling out bug fixes.
Tip
To manage the deployment of code changes, clone an existing code package, give it a new name, and improve its code. When you are ready to deploy the clone, use "alterCodePackage" to activate it. Assign the clone to the transforms, jobs, and triggers where the original code package is used. Deactivate the old code package when it is no longer in use.
Each time you alter the "code" or "codeFormat" properties, the server increments the revision 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 revision number or write the change to the code package history.
You cannot alter the "codeName", "codeType", "codeLanguage", and "serviceName" properties.
Altering the "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.
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. The server loads active code packages into instances of the language runtime, such as the Google V8 JavaScript engine.
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.
To rename a code package, use the "cloneCodePackage" action to create a new one. Then use the "alterCodePackage" action to deactivate the existing one.
To version a code package, use the "cloneCodePackage" action to create a new one with a major version number appended to its name, such as "Convert Celsius To Fahrenheit V2". Then use the "alterCodePackage" action to deactivate the existing one. Note that a code package's "version" property is a revision number that the server automatically increments each time you modify a package's "code" property. The "version" property does not change when you modify a package's "codeStatus", "comment", "description", and "metadata" properties.
Request examples
{
"api": "admin",
"action": "alterCodePackage",
"params": {
"databaseName": "faircom",
"ownerName": "admin",
"codeName": "convertTemperature",
"codeLanguage": "javascript",
"codeType": "getRecordsTransform",
"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": "developing"
},
"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": "convertTemperature2",
"comment": "Modified the code and changed the name back",
"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"
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"databaseName": "faircom",
"ownerName": "admin",
"codeName": "convertTemperature",
"codeLanguage": "javascript",
"codeType": "getRecordsTransform",
"codeStatus": "active",
"comment": "optional change comment",
"description": "optional new description",
"metadata": {},
"code": "optional new code to replace old code",
"codeFormat": "utf8"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"comment": "The new comment replaces the old comment."
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "active"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "testing"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "deprecated"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "developing"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "inactive"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"codeStatus": "deleted"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"metadata": {
"keyword": "temperature"
}
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"comment": "",
"description": "",
"metadata": {}
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"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
}
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"requestId": "1",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature",
"comment": "Changed the name from convertTemperature to convertTemperature2.",
"description": null,
"metadata": null
},
"requestId": "1",
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}{
"authToken": "replaceWithValidAuthToken",
"debugInfo": {
"request": {
"authToken": "replaceWithAuthTokenFromCreateSession",
"api": "admin",
"action": "alterCodePackage",
"params": {
"codeName": "convertTemperature2",
"comment": "Modified the code and changed the name back",
"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}"
},
"debug": "max"
}
},
"errorCode": 0,
"errorMessage": ""
}Use the alterCodePackage API action to update stored JavaScript code in the server
Property | Description | Default | Type | Limits (inclusive) | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
contains the source code stored in the server |
| Json string | ||||||||
specifies the encoding of the code in the code property |
| string | "utf8" | |||||||
specifies the programming language of the code in the | Required - No default value | enum |
| |||||||
specifies the name of the code package | Required - No default value | string | ||||||||
specifies the status of the code. The server only runs code with a status of |
| enum |
| |||||||
specifies how and where a FairCom server can run the JavaScript code | Required - No default value | enum |
| |||||||
describes the latest change to the code |
| string | ||||||||
specifies the name of the database | Defaults to the session's | string | ||||||||
describes the code package |
| string | ||||||||
contains user-defined properties that add keywords and tags about the code package |
| string | ||||||||
when specified, the server renames the code package to the new name |
| string | ||||||||
specifies the name of the owner | Defaults to the session's | string | ||||||||
specifies the name of the code service that provides the programming language runtime environment |
| string | ||||||||
specifies the number of bytes for the session to allocate initially for its transform buffer |
| integer |
"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.
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:
"integrationTableTransform"runs JavaScript code when a record is inserted into an integration table."getRecordsTransform"runs JavaScript code when a"getRecords..."action is called.
"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. See "Use "codeStatus" to make a package runnable".
"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.
The "serviceName" property is a case insensitive, optional property that defaults to "javascript". It specifies the name of the code service that provides the programming language runtime environment.
The "serviceName" property maps to a section in the services.json file called "codeServices" that defines which programming languages are available in the product.
"codeServices": [
{
"serviceName": "javascript",
"serviceLibrary": "v8transformservice.dll",
"enabled": true
}
],In services.json, multiple code language services can be created with different "serviceName" properties, such as "javascript", "javascript2023", and "javascript2027". This allows the developer of a code package to do things like use "javascript" to specify the latest version of the JavaScript code service or target a specific version of the JavaScript engine using a more specific "serviceName".
Each service may use the same or different dynamic libraries (.dll, .so, or .dylib) to provide the programming language runtime. The same dynamic library may also be reused in other services, such as transform services.
The "transformBufferInitialBytes" property is optional and defaults to 0. It is a positive integer that specifies the number of bytes for the session to allocate initially for its transform buffer. Omit this property or set it to 0 when you do not plan on using the "transformCodeName" property to transform the JSON returned from the "getRecords..." actions. If you plan on transforming the JSON, you can set the "transformBufferInitialBytes" property to the number of bytes that you anticipate the server will need to store the results of each transform. If the server needs more memory, it automatically increases the buffer size; thus, this property is an optimization that helps prevent the server from doing expensive memory allocations.