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.
Common code package actions
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 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.
Code package types
FairCom Edge and FairCom MQ support code package types called getRecordsTransform and transform.
"getRecordsTransform" package
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 using the mapping data in records to JSON documents.
The server assigns the array of JSON objects to a variable named sourceRecords in the V8 engine. The server assigns the JSON DB request object to a variable named requestObject. The JavaScript code optionally reads properties in the requestObject variable, such as "responseOptions", to determine how it should encode binary, numeric, and date values. The JavaScript code transforms the array of JavaScript objects in sourceRecords and writes the array of transformed records into a variable named transformedRecords. The server adds the value in transformedRecords to the "data" property that it returns from the "getRecords..." action.
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 error, the JSON DB action stops processing records. The server puts the value of transformedRecords in the "data" property and returns the error information. 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.
"transform" code package
FairCom Edge and FairCom MQ support a code package type called "transform". A 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.
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 and is converted into JSON using the JSON DB conversion rules. The server assigns the array of JSON objects to a variable named sourceRecords in the V8 engine and assigns the JSON DB request object to a variable named requestObject. The JavaScript code optionally reads properties in the requestObject variable, such as "responseOptions", to determine how it should encode binary, numeric, and date values.
The JavaScript code transforms the array of JavaScript objects in sourceRecords and writes the array of transformed records into a variable named transformedRecords. The server adds the value in transformedRecords to the "data" property that it returns from the "getRecords…" action. 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 error, the JSON DB action stops processing records. The server puts the value of transformedRecords in the "data" property and returns the error information. 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.