Skip to content

ScriptForge

Developer ScriptForge

Use ConnexCS ScriptForge to write ECMAScript 2015 (ES6) (aka JavaScript) and execute it in a secure sandbox on the server. It's designed to have low latency and high throughput.

It's made for scripts and small applications. Any larger applications are best executed on external hardware through ScriptForge.

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

It's designed to work as FaaS (Functions as a Service), and our redundant infrastructure handles your application's auto scaling needs.

Developer Documentation

ConnexCS offers several libraries specifically for use with ConnexCS. Developer API Documentation is available here.

Available Modules

You can include some more modules (from npm), available for applications and drivers only.

The purpose is to keep the sandbox lightweight and include only the necessary modules:

Modules
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 > example applications. Below is a list of some use cases. But with a Turing Complete language, the possibilities are endless.

  • Do Not Call Lists
  • Custom Fraud Detection
  • Internal Automations
  • Capture and process the Control Panel and Customer Portal forms
  • Inbound and Outbound Call Filtering
  • Class 5 Programmable Voice Applications
  • DID Drivers
  • Time of Day Restrictions

Coding Basics

Scripts and Apps typically start in the main() function and expect to return a promise. The first parameter is typically an object called data.

Throwing Errors (Class 4)

Follow the following format; [SIP code] :space: [Error Message], for throwing errors.

For example, to throw a 404 Not Found, you can use the following

throw new Error('404 Not Found');

(SIP: Session Initiation Protocol, DID:* Direct Inward Dialing)

Class 4 Routing (Routes and Direct Inward Dial)

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.

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

You can use Programmable Voice to write smart voice applications controlled in modern JavaScript.

The call and the Programmable Voice script are both executed simultaneously, 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 the platform has finished executing the operation.

See the ConnexCS ScriptForge documents for more JavaScript examples.

Second parameter is a ctx object

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

Potential Sync Issues

To avoid the system losing synchronisation with your script and the connection crashing, execute ALL async functions with await. If it isn't implemented correctly, it affects that billing and call stability.

Form Submission

Used to receive data from Form Builder in ConnexCS.

You can view it in the control panel or customer portal.

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

Configuration

Build Script

  1. To add a script, click .
  2. Specify the script Name.
  3. Select the Type:

    • Script- This is the fastest way to execute custom code and is "synchronous" execution. This is mainly 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.
  4. Click Save.

  5. Select your script from the list.
  6. Enter the code of your script.

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

    {"routing":{}}
    
  7. Global Routing Priority means the script will run for every single call. You have 3 options to choose from:

    • You can disable it if you don't want to use it.
    • Run first or Run Last means this script will run first or after the Script Forge enabled in the Routing section.
    • The App field allow you to integrate the created applications with the ScriptForge.
  8. Click the green arrow to Save and Run.

  9. You can view the results onscreen.

The Schedule option allows to you run your Script Forge based on pre-determined dates in month, days of a week and you can even select the time by selecting the values of minutes and hours from the drop-down menu.

Assign the Script to a Customer

  1. Select Management Customer [Customer Name] Routing
  2. Select a Rate Card from Ingress Routing.

    alt text

  3. Go to ScriptForge

  4. Select the script.
  5. Set the Timeout to specify the duration you want it to run before it times out.
  6. Enter the Timeout Action manually and format it as [sip response code] [sip response message].
  7. Click Save.

Assign the script to other functions

ScriptForge was initially designed to run from the routing-engine only, but it's available for the following scenarios:

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

Manipulating headers from ScriptForge

This feature helps you manipulate or remove headers.

Below are some examples for removing headers for all or specific destinations.

function main(data) {

// Delete headers for ALL destinations
    data.remove_headers = [
        {key: 'X-Customer-ID'}
    ]; 
// Delete headers for first destination
    data.egress_routing[0].remove_headers = [
        {key: 'X-Customer-ID'}
    ];
// Add Headers for ALL Destinations
    data.headers = [
        {key: 'X-Customer-ID', value: '1234'}
    ];
// Add Headers for first destination
    data.egress_routing[0].headers = [
        {key: 'X-Customer-ID', value: 1234}
    ];
// If you want to replace a header, you must remove it, then add it.
    return data;
}

Originate a Call via an API using ScriptForge

The API Dialing feature sends an API request to the ConnexCS Platform for their customers to place a call via the API.

For this feature, write an API in ScriptForge for connecting the company to their customer via the ConnexCS Platform using this API (in ScriptForge).

ScriptForge uses the originate feature for originating the call.

You need to include the Company ID,the Server where the call will be sent, Destination, CLI, and Extension in the script.

flowchart TD
 A[End Customer] --> B[Customer's Dialer/Application]
    B --> C[Dialer makes an API request via HTTP]
    C --> D[API-HTTP API request hits the ConnexCS platform]
    D --> E[ConnexCS platform runs ScriptForge]
    E --> F[ScriptForge uses ScriptForge API to place a call]
    F --> G[The API talks to the ConnexCS Class 5 Infrastructure]
    G --> H[Class 5 then talks to the Cx Customer Class 4 Infrastructure]
    H --> I[Call placed]

Building the API Code

  1. Login to your account.
  2. Go to Developer ScriptForge IDE ScriptForge.
  3. Click on the blue + button.
  4. Enter the Name for the script in the Basic Tab.
  5. You can use the Schedule tab to run your script.
  6. Click on Save.
  7. Click on the created script Calling API.

  8. Enter the below code:

/* This ConnexCS Library makes it easy to place a call */
const originate = require('cxOriginate');
/*
    Simple Key/Value pairs, where the Key is a private secret,
    and the value is the Customer ID.
*/
const apiKeys = {
    'secret-key': 1234
};
//async function main (data) {
    /* Authorizing the key */
    const companyId = apiKeys[data.apiKey];
    /* If the company does not exist, throw an Error*/
    if (!companyId) throw new Error('401 Unauthorized');
    /*
        If the destination does not exist, throw an Error
        The destination is the telephone number to be dialled
    */
    if (!data.destination) throw new Error('Missing Destination');
    /*
        If the CLI does not exist, throw an Error
        The CLI is the form number of the phone call.
    */
        if (!data.cli) throw new Error('Missing CLI');
    /*
        If the extension does not exist, throw an Error
        The external is the second leg destination where the
        connected call will then be delivered to.
        For example, a queue.
    */
    if (!data.extension) throw new Error('Missing Extension');
    /*
        Use the ConnexCS library to place the call.
    */
    var result = await originate.originate(companyID, 'enter server details the calls will be sent to', data.destination, data.cli, data.extension);
    /*
        Confirm that everything worked okay.
    */
    return {status: 'OK'};
}

9.Click on Save and Run.

10.You can access this feature on your Customer Portal using the UUID. We use the UUID to access ScriptForge from the customer portal URL as an API unauthenticated. For example, your Customer Portal URL is https://api.xx.yy/api/script/uuid and the code will be published here.