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:

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 
}

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¶

Assign the Script to a Customer¶

1. Select Management Customer [Customer Name] Routing

2. Select a Rate Card from Ingress Routing.

   

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.