Concepts
Concepts for creating code packages that provide custom features for FairCom servers.
The FairCom JSON ADMIN Code Package API prepares user-supplied source code for running in a FairCom server. JavaScript code can be put into a code package and referenced by name. In FairCom Edge and FairCom MQ servers, you can create a code package to transform data inserted into integration tables. In all FairCom servers you can create a code package to transform the JSON returned by "getRecords..." actions in the JSON DB API.
The Code Package API can store and manage source code in any language. Currently, the FairCom server only runs code packages containing JavaScript code that runs in the Google V8 engine.
The type of code package defines where and how the server runs it. For example, a transform code package runs when FairCom Edge or FairCom MQ inserts a record into an integration table. Your source code must meet the requirements of the type of code package. The server currently supports the "transform" and "getRecordsTransform" types of code packages.
Each Code Package has a name that uniquely identifies it. The fully qualified name consists of three properties: "databaseName", "ownerName", and "codeName". This design enables you to reuse the same "codeName" in different environments.
It is common to use different databases for each environment, such as DEV, TEST, STAGE, and PROD. It is also common to create an application account for each application and use the application account name as the "ownerName". This approach allows you to run multiple environments and applications on a single FairCom server. Similarly, multitenant applications use a customer's account as the "ownerName" so they can host multiple customers in multiple environments on one FairCom server. Including the "databaseName" and "ownerName" in the fully qualified name of each object enables you to write your code once to work with a standard set of object names and and it will work the same in all environments.
When you run the "createSession" action to create a jsonAction session on a FairCom server, you set the "defaultDatabaseName" and "defaultOwnerName" properties to the environment and application you want the session to use. To make your jsonAction code portable across environments and applications, you should omit the "databaseName" and "ownerName" properties so the server will use the default session values.
For example, a customer may create an account named "shoppingCart" for a shopping cart microservice. The customer can deploy a code package named "transformTemperature" to the "dev" database with the owner of "shoppingCart". When it is time for QA, the customer can clone the code package to the "test" database and "shoppingCart" owner for testing. When the code has been tested, the customer can clone the code package to the "prod" database and "shoppingCart" owner to release it for use. If another application wants to use the code package, you can clone it for use in that application's owner name.
A FairCom server always runs the latest version of a code package.
To upgrade a code package with no interruption to service, use "alterCodePackage" to update its code. The server automatically starts running the new code as soon as it finishes running processes using the old code.
You can revert a code package to a previous version by running the "revertCodePackage" action, which copies the code of a previous version and makes it the latest version. The server automatically starts running the reverted code as soon as it finishes running processes using the old code.
If you want to run multiple versions of the same code package simultaneously in the same database and owner, you can clone an existing code package and rename it with a variation indicator at the end of the name, such as "My code package - V1.2".
A FairCom server uses the code package's "codeStatus" property to determine if it can run the code package. This is necessary because a FairCom server automatically runs code packages in response to server events, such as a transform, job, or trigger.
The "codeStatus" property follows the software development lifecycle.
"developing": A code package starts out with a"developing"status so you can modify and save it knowing the server will not run it. Move a code package back to"developing"when you want the server to stop running a code package because you need to fix a serious bug."testing": Move a code package to"testing"when you are ready for the server to start running it in response to server events."active": Move a code package to"active"when you want the server to run the code package and have confidence the code is ready for production."deprecated": Move a code package to"deprecated"when you want the server to continue to run the code package, but you plan on removing or replacing it in the future."inactive": Move a code package to"inactive"when you want the server to stop running the code package."deleted": Move a code package to"deleted"when you want the server to stop running the code package and you do not want anyone to run this code again.
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 test a running code package, clone it, improve it, and test it in a non-production environment. When it is ready, use "alterCodePackage" to assign the new code to the running code package.
Tip
Immediately deactivate code that harms data to stop the server running the code again.
Warning
Deactivating a code package causes processes that rely on the code package, such as transforms, triggers, and jobs, to return an error.
Each time you alter the "code" property, the server increments the version number of the code package and stores the previous version in the code package history. Each code change automatically increments the version number of a code package. If its "codeStatus" is set to "testing", "active", or "deprecated", the server starts running the code package.
Each time you alter the other code package properties, such as "codeStatus" and "metadata", the server updates them in place; it does not change the version number or write the change to the code package history.
You can choose whether you reuse a code package or clone it.
To reuse a code package, assign its name to an event, such as a query transform. You can reuse a code package in multiple databases and owners.
Tip
It is rarely a good idea to use the same fully qualified name of a code package across DEV, TEST, STAGE, and PROD environments because each environment is in a different stage of the development lifecycle and typically needs to run different code. Thus, use the same "codeName" in these environments and let the environment defaults set the "databaseName" and "ownerName" properties.
To create a code package, use "createCodePackage".
To modify a code package, use "alterCodePackage". The server tracks changes you make to the code package and assigns a version number to each change. Each time you alter an existing code package, the server increments the integer version number, adds the change to the version history, and updates the current code with the new code. You cannot modify the version number. If you want to reset the version number, clone the code package.
To deactivate a code package, use "alterCodePackage" to set its status to "developing", "deleted", or "inactive". The server finishes running existing processes that use the code package and prevents the code package from running again.
To activate a code package, use "alterCodePackage" to set its status to "deprecated", "testing", or "active".
To delete a code package, use "alterCodePackage" to set its status to "deleted".
To undelete a code package, use "alterCodePackage" to set its status to "deprecated", "testing", or "active".
To clone a code package, use "cloneCodePackage". The server always runs the latest version of a code package. If you want to run multiple variations of the same code package simultaneously, you can clone an existing code package and rename it with a variation indicator at the end of the name, such as "My code package - V1.2".
To list the latest versions of code packages, use "listCodePackages".
To list previous versions of code packages, use "listCodePackageHistory".
To view code and where it runs, use "describeCodePackages" to return the code, the properties, and each location where the server uses the code package.
To view code history, use "describeCodePackageHistory". It returns the code, version, and the properties.
To revert a code package to a known good version, use "revertCodePackage". You can revert a code package when a new version is misbehaving. The server increments the integer version number, adds the current code to the version history, and updates the current code with the earlier version of the code. The server finishes running the old code package and immediately starts using the new code package for new processes.
To fix misbehaving code, you can deactivate a code package. After the server finishes running processes that use the package, the server stops running the code in the package and will not run the code in the future. Fix problems with the code and use the "alterCodePackage" action to save the new code and activate the code package so it can run again.
FairCom Edge and FairCom MQ support code package types called getRecordsTransform and integrationTableTransform.
A "getRecordsTransform" code package contains JavaScript code that transforms a batch of records retrieved during a JSON DB "getRecords..." action. The server retrieves a maximum of 10,000 records and converts them into an array of JSON objects. Each object represents one record that the server converted into JSON by mapping data in records to JSON documents.
The server assigns the array of JSON objects to a variable in the V8 engine named records. There is one object for each record returned by the "getRecords..." query. The JavaScript code transforms the array of JavaScript objects in records and writes changes back to records. The server adds the value in records to the "data" property that it returns from the "getRecords..." action.
The JavaScript code can change the value of records to any valid JSON value and the FairCom server will return it. For example, the JavaScript code can calculate an average value from the records and assign it to the records variable.
The serve also creates a variable named requestObject and assigns the JSON DB "request" object to it. The JavaScript code optionally reads properties in the requestOjbect variable, such as "responseOptions", to determine how it should encode binary, numeric, and date values. The "requestId" property is also useful to JavaScript code because the application can set it to any JSON value. Thus, an application can set the "requestId" property to an object to communicate additional information to the transform process.
The server repeats this process as many times as necessary to retrieve the number of records requested by the "getRecords…" action.
If the JavaScript code throws an uncaught exception, the JSON DB action stops processing records and returns the error information in the "errorCode" and "errorMessage" in the response. You may find it more useful to catch all errors in your JavaScript code and add error information to records.
The server puts the value of records in the "data" property. Thus, when the JavaScript code encounters an error, it can add record data and state information to transformedRecords to help developers troubleshoot the record that triggered the error.
FairCom Edge and FairCom MQ support a code package type called "integrationTableTransform". An "integrationTableTransform" code package contains JavaScript code that transforms data in a record in an integration table.
When a record is inserted into an integration table, the server runs the JavaScript code. The code receives the inserted record from the server, takes data from fields in the record, transforms the data, and writes the transformed data to other fields in that record.
Transform code is JavaScript code that receives two JavaScript objects from the server. One of these objects is named record, and the other is named transformStep. The record object contains all the fields in the current record, and the transformStep object includes all properties in the transform step.
The transform code uses the settings in the transformStep object to guide its behavior. Users can use predefined properties and their own properties in the stepParams object in the transformStep to configure their JavaScript code. The code reads field values from the record object, transforms the data, and writes the transformed data to other fields in the record object. If there is an error, the code adds an error object to the JSON array in the log field of the record object and sets the error field to true. The server reads the changed properties in the record object and writes the changes to the record that it inserts into the integration table.