Skip to main content

Creating Scripts

Creating a New Script#

To create a new script, you can right click the Script folder in a Project, and select ether "Create New Script" or "Create New Backend Script". A new script will be created in the Item Service and will appear in the extension tree. Right clicking the script in the tree and selecting Open will get the editable portion of the script to your local workspace and open it in an editor.

Starting in version 4.3, there are two types of scripts: Client Scripts and Backend Scripts. Backend Scripts are for use with the Object Model API Service and the Datasources Service Orchestrators. Client Scripts are ES Modules and Backend Scripts are vanilla JavaScript.

Be sure to create the right kind of script based on where it will be used.

The script create commands will populate a corresponding scaffolded script file.

For 'Create New Script' the new script will automatically be populated with a scriptModule and default export of the scriptModule. There will also be initial scripts added to the scriptModule for each type of script the extension supports running.

Here is an example:

let scriptModule = {    async sampleScript(input, libraries, ctx, callback){
    }}
export default scriptModule

You may include as many scripts within the scriptModule as you like, so long as their function names are unique.

For 'Create New Backend Script' the new script will automatically be populated with two functions, one of which is a getRunnableScripts functon which is necessary if you wish to be able to run and test the scripts through VS Code.

function scriptFunction(input, libraries, ctx) {
    return 'Hellow World'
}

function getRunnableScripts() {
    return [
        {name: 'Script', script: 'scriptFunction'}
    ]
}

You can add as many functions as you like to the backend script file, and those with a corresponding entry in the getRunnableScripts array will be able to be run and tested in VS Code.

Backend scripts will appear with '<b>' appended in the extension tree.

Script Signatures#

Scripts should have the the correct signature for where the script will be used. Scripts can be either async or sync.

async sampleScript(input, libraries, ctx, callback)
sampleScript(input, libraries, ctx, callback)

Script Parameters#

  • input (optional) : An optional input to the script. This should be either a javascript object or a JSON object.

  • libraries : Libraries that the script can use. Client and Backend Scripts have different sets of libraries.

    • Client Script libraries:

      • PlatformAPI: All the Platform API libraries.
      • IafScritpEngine: Convenience methods for use in scripts
      • UiUtils: Functions for reading files from disk and import and export of XLSX files

    • Backend Script Libraries:

      • PlatformAPI: All the Platform API libraries.
      • IafScritpEngine: Convenience methods for use in scripts
      • CoreUtils
      • fs
      • path
      • unzipper
      • uuidv4
      • _
      • moment
      • dayjs
      • mingo
      • ajv
      • chrono

  • ctx : information about the current user's ctx.

  • callback (optional) : An optional callback function the script can call to return partial results.

Using Libriaries#

The libraries can be used in a script in the following ways:

async script(input, libraries, ctx, callback){
    let result = libraries.PlatformApi.IafPassSvc.getCurrentUser(ctx)
}
async script(input, libraries, ctx, callback){
    let { PlatformAPI } = libraries
    let result = PlatformApi.IafPassSvc.getCurrentUser(ctx)
}
async script(input, libraries, ctx, callback){
    let { IafPassSvc } = libraries.PlatformApi
    let result = IafPassSvc.getCurrentUser(ctx)
}

The ctx Context Object#

The ctx object contains information about the current user's context, such as the project in which the user is working. It is important that this ctx object be passed to every script and to every Platform API function. When scripts are run through the browser this ctx object will managed automatically by the browser application. When running via the IDE Extension, it will manage the user's context and pass it to all scripts.

Be sure to reference the PlatformAPI documentation to see which parameter the ctx should be passed as to any given function. It is usually the last or second to last parameter.

Script Return Values and Callbacks#

Every script should have at least one return statement with the results of the script. More than one return statement can be used.

async script(input, libraries, ctx, callback){
    if (!input) return "Script input is required!"    else {
        /*         * code that does work and produces "result"        */        return result    }}

Callbacks can be used to return partial data or progress to the application running the script. It is best to make sure that a callback exists before using it.

async script(input, libraries, ctx, callback){
    /*      * code that fetches first 100 results    */
    if (callback) callback(firstHundred)
    /*      * code that fetches second 100 results    */
    if (callback) callback(secondHundred)}