alterCodePackage

Update 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

Typical

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

Minimal

{
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "comment": "The new comment replaces the old comment."
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Run a package in production

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "active"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Run a package for testing

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "testing"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Deprecate a package and keep running it

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName":"convertTemperature",
    "codeStatus": "deprecated"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Save a developed package but do not run it

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "developing"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Stop running and using package

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "inactive"  
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Delete a package

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "codeStatus": "deleted"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Change package metadata

{ 
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "metadata": {"keyword":"temperature"}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Remove package comment, description, and metadata

{
  "api": "admin",
  "action": "alterCodePackage",
  "params": {
    "codeName": "convertTemperature",
    "comment": "",
    "description": "",
    "metadata": {}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Change package comment, description, and metadata

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

Change code

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

 

Response examples

Typical

{
  "debugInfo": {
    "request": {
      "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",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Minimal - change package comment

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "comment": "The new comment replaces the old comment."
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Run a package in production

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "active"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Run a package for testing

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "testing"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Run a package for testing

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "testing"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Deprecate a package and keep it running

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "deprecated"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Save a developed package but do not run it

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "developing"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Stop running and using a package

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "inactive"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Delete a package

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "codeStatus": "deleted"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Change package metadata

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "metadata": {
          "keyword": "temperature"
        }
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Remove package comment, description, and metadata

{
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "comment": "",
        "description": "",
        "metadata": {}
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Change package comment, description, and metadata

{
  "debugInfo": {
    "request": {
      "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",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Change code

{
  "debugInfo": {
    "request": {
      "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",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

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. Optional with default of "" string 1 to 8,388,096 bytes

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"

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. Required - No default value string

"javascript"

"json"

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.

 Required - No default value string 1 to 64 bytes

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". Optional with default of "developing" string

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

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:

 Required - No default value string

"integrationTableTransform"

"getRecordsTransform"

comment

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

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

description

 The "description" property describes objects such as code packages, labels, or things. The server indexes this field with a full-text index so that you can search for any word or phrase. You cannot use this property for filtering in the Thing API.

Optional with default of "".

"unknown" for Thing API 

 string

0 to 65,500 bytes

1 to 512 bytes for the Thing API 

metadata

 The "metadata" property 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. Optional with default of {} object 0 or more key/value pairs

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

 

Was this article helpful?

Give feedback about this article

Related Articles