"alterCodePackage" (JSON Action)

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

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

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

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

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

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

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

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

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

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

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

{
  "requestId": "1",
  "debugInfo": {
    "request": {
      "api": "admin",
      "action": "alterCodePackage",
      "params": {
        "codeName": "convertTemperature",
        "comment": "Changed the name from convertTemperature to convertTemperature2.",
        "description": null,
        "metadata": null
      },
      "requestId": "1",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

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

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

"codeFormat" is an optional string that 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.

"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 "codeName" property is a required, case-sensitive string between 1 and 64 bytes containing 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.

The "codeServices" property is an optional array of objects that specifies which programming languages are available in the product.

The "enabled" property is an optional Boolean that specifies whether or not the feature is enabled. The example below enables the TLS feature.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

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.

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

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:

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

The "databaseName" property is an optional string from 1 to 64 bytes that 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.

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

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

The "ownerName" property is an optional string from 1 to 64 bytes that specifies the account that owns an object, such as a table or code package. If it is set to null or is omitted, it defaults to the account that created the JSON Action session, see "createSession" and the "defaultOwnerName" property. 

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.

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.