Skip to content

ScriptForge

Developer ScriptForge

ConnexCS ScriptForge allows you to write ECMAScript 2015 (ES6) (aka JavaScript) which is executed in a secure sandbox on the server. It is designed to be low latency and high throughput.

It is made for scripts and small applications. Any larger applications are best executed on external hardware with Scriptforge intermediating it.

A fair-usage policy applies and your script may not function as expected if there is unnecessary resource utilisation or if there are any attempts to break the sandbox.

It is design to work as FaaS (Functions as a Service) and auto-scaling your application is handled by our redundant infrastructure

Developer Documentation

ConnexCS provide a number of libraries specifically for use with ConnexCS. Developer Documentation is available here.

Available Modules

You can include some additional modules (from npm), available for applications and drivers only. Our objective is to keep the sandbox lightweight and only include modules which are necessary:

  • axios
  • axios-cookiejar-support
  • card-validator
  • csv-parse/lib/sync
  • data-forge
  • decompress-zip
  • elasticemail-webapiclient
  • fast-csv
  • fast-toml
  • ftp
  • helpscout-2.0
  • moment
  • rss-parser
  • soap
  • stripe
  • tough-cookie

Sample Scripts

You can find sample scripts in our GitHub repository for example applications. A few uses cases are included below, however with a Turing Complete language, the possibilities are endless.

  • Do Not Call Lists
  • Custom Fraud Detection
  • Internal Automations
  • Capture and Process control panel and customer portal forms
  • Inbound & Outbound Call Filtering
  • Class 5 Programmable Voice Applications
  • DID Drivers
  • Time of Day Restrictions

Usage

ScriptForge was initially designed to run from the routing-engine only, however it is available for the following scenarios:

Scenario Usage
Class 4 Routing (Termination) - (App or Script) Management Customer [Your Customer] Routing [Your Route] ScriptForge
Class 4 Routing (Origination) - (App or Script) Management Customer [Your Customer] DID [Your DID] ScriptForge
Class 5 Programmable Voice - (App only)
Drivers - (App only) Currently available for Alert & DID

Execution Types

Script

This is the fastest way to execute custom code and is "synchronous" execution. This should mainly be used for manipulations or calculations. It can't use libraries or work with Promises.

App

Feature rich applications which can include a preset (whitelist) of available modules, the penalty of the extra features is a slightly higher latency.

Driver

A driver works as an intermediary between ConnexCS and any external system. You can write drivers to bridge the ConnexCS DID provisioning system to a provider of your choice or build more complicated alerts.

Coding Basics

Script & Apps typically start in the main() function and expects a promise to be returned. The first parameter is typically an object called data.

Throwing Errors (Class 4)

Errors can be thrown in the format [SIP code] :space: [Error Message], for example to throw a 404 Not Found you can use the following

    throw new Error('404 Not Found');

Class 4 Routing (Routes & DID)

After the routing engine has executed its main function, the system will run the custom ScriptForge script. This presents data as the output to the routing engine and expects the same object structure to be passed along.

function main (data = {}) {
    // data.routing contains the same data you will find in the Logs
    // in the Raw Data Section
    return data;
}

Class 5 Programmable Voice

Programmable Voice allows you to write smart voice applications controlled in modern JavaScript. The execution of the Programmable Voice script is done synchronously with the call, simplifying the entire process. This means that (for example) you would initially run an await answer(), it would not progress to the next line until our platform has finished executing the operation. See the ConnexCS ScriptForge documents for additional JavaScript examples.

Second parameter is a ctx object

function main (data = {}, ctx) {
    // ctx contains class 5 ctx object 
}

Potential Sync Issues

Ensure that ALL async functions are executed with await, otherwise the system will lose the synchronised state with your script and the connection will crash. If not implemented correctly, billing and call stability could be impacted.

Form Submission

Used to receive data from Form Builder in ConnexCS, which can be displayed in the control panel or customer portal.

function main (data = {}) {
    // data contains object containing key/value pairs from the form. 
}

Driver

A driver is a module export which may contain several pre-defined functions dependent on the integration, flow is an example for DID Driver.

module.export = {
    search: async function ({number}) {
        // Returns Array of Objects, e.g [{did:'1234'}]
    },
    allocate: async function ({did}) {
        // The information returned by this function will be passed to 
        // https://api-docs.connexcs.com/#api-Did-Create
    },
    release: async function ({did}) {
        // Returns True / False
    },
    list: async function () {
        // Returns Array of Objects, e.g [{did:'1234'}]
    }
}

Configuration

Build Script

  1. Select Developer ScriptForge
  2. Add a script by clicking +.
  3. Fill in the script's name and type, then click Save.

    alt text

  4. Select your script from the list.

  5. Enter the code of your script
  6. Click the green arrow to Save and Run.
  7. The results will be shown onscreen.

If script shows an error, add this then run the script again:

{"routing":{}}

Assign the Script to a Customer

  1. Select Management Customer [customer] Routing
  2. Select a rate card from the table.

    alt text

  3. Go to ScriptForge

  4. Select the script
  5. Set the Timeout to specify how long it will run before timing out
  6. The Timeout Action is entered manually and must be formatted as [sip response code] [sip response message].
  7. Click Save.