Skip to main content

Container Application Blocks

For the impatient

You may explore this data model via the API Playground, by clicking here

The Cloudonix Container Application runtime supports several different "languages" to allow developers to quickly deploy simple application by mix-and-matching static, declarative and fully programmable block types in the same application.

The various available block types are described here below.

Static Document​

Runtime: static​

The static document block type allows the developer to put in static CXML documents that will be run directly as-is on a voice call.

The code in this block type must be a well-formed and valid CXML document.

Example Code​

<?xml version="1.0"?>
<Response>
  <Gather action="main-routing" input="dtmf" numDigits="1">
    <Say>Welcome to Famous Company Ltd. For sales press 1, for customer support press 2, and for billing press 3.</Say>
  </Gather>
</Response>

Selection Switch​

Runtime: select​

The selection switch block type is useful as the action for a <Gather> operation - it will read the input from a subscriber collected by the <Gather> operation and redirect the application flow to another action depending on the input, without needing to write any code to handle the logic.

The code in this block type is a mapping of every possible input to a relative or absolute URL. Such map is composed of a set of text lines (ending with a new-line character) where each line is composed of the input to match, followed by a color (:) and the destination action.

Example Code​

1: sales-queue
2: support-menu
3: dial-billing

Note:​

This runtime also supports providing the mapping as a JSON object containing pairs of string keys and string values.

Forward to HTTP​

Runtime: forward​

For developers that have existing deployed voice applications, written for CXML or any compatible API, it may be useful to offload some of the blocks to a remotely accessible application while handling most of the logic and configuration as a hosted voice application. For such cases the foward runtime allows a block to proxy a remote HTTP endpoint.

The code in this block type must be a URL with the http or https schema that will receive a CXML application request and must respond with a well-formed and valid CXML document.

Example Code​

https://example.com/application/support-menu

Javascript Lambda​

Runtime: javascript​

This fully programmable block type supports running code that is ECMAScript 2018 compatible (Javascript version 9). The runtime will load the block's code into a Javascript VM and will then execute it using semantics similar to AWS Lambda, and will use the result as the CXML document to be executed by the Cloudonix Voice Application runtime.

Calling Convention​

The Javascript runtime will expose an object as the global value exports then evaluate the block's code. The code should set up a handler function and assign it to exports.handler - the function should have the signature function(Jevent, context, callback).

After evaluating the code, the Javascript runtime will call the handler function and will pass it the following parameters:

  • event : an object containing the CXML application request details. It is read-only and contains the following member fields:
  • body : the Voice Application request as a JSON formatted string.
  • headers : the Voice Application request headers as a standard Javascript object (map of string keys to string values).
  • httpMethod : the method used to make the Voice Application request - either GET or POST.
  • parameters : the Voice Application request parameters as a standard Javascript object (map of string keys to string values).
  • path : contains the request path to the block being run, within the application - i.e. / followed by the block name.
  • pathParameters : an empty object provided as backward compatibility for AWS Lambda code.
  • queryStringParameters : the same as parameters, provided as backward compatibility for AWS Lambda code.
  • requestContext : an empty object provided as backward compatibility for AWS Lambda code.
  • stageVariables : an empty object provided as backward compatibility for AWS Lambda code.
  • context : a read-write Javascript object. No specific values are exported through this object.
  • callback : a callable with the signature function(error, response) that should be used by the code to submit the result of the block execution.

The handler function should compute the correct response to the application request and submit a CXML document by calling the callback function with a null value for the first parameter and the response document as a string for the second parameter. If an error has occured during processing, the callback function should be called with just one parameter being a Javascript Error object describing the error - that error would be propagated to the error field of the Cloudonix session object of the call.

Example Code​

function preamble() { return '<?xml version="1.0"?>\n'; }
function response(content) { return `<Response>\n${content}\n</Response>\n`; }
function dial(content) { return `<Dial>\n${content}\n</Dial>\n`; }
function queue(name, url) { return "<Queue " + (url?`url="${url}"`:'') + `>${name}</Queue>`; }
function getQueueName(event) { return "sales"; }
exports.handler = function(ev, ctx, callback) {
  try {
    callback(null, preamble() +
      response(dial(queue(getQueueName(ev), "queue-announce"))));
  } catch (err) {
    callback(err);
  }
};

Ruby Lambda​

Runtime: ruby​

This fully programmable block type supports running code written in Ruby (version 2.5). The runtime will load the block's code into a Ruby VM and will then execute it by calling a handler method. The return value from the handler method will be used as the CXML document to be executed by the Cloudonix Voice Application runtime.

Before executing the Ruby code of the block, the runtime will use Gem::DependencyInstaller to install all the Ruby gems that the code requires.

Calling Convention​

The Ruby runtime will require rubygems and rubygems/dependency_installer, then call Gem::DependencyInstaller to install all the gems for which the block's Ruby code calls require on (installed libraries are cached locally for performance). The runtime will then evaluate the block's Ruby code and expects the code to define a global method with the signature handler(event, context).

After evaluating the code, the Ruby runtime will call the handler function and will pass it the following parameters:

  • event : a Hash containing the CXML application request details. It is read-only and contains the following keys and values:
  • body : the Voice Application request as a JSON formatted string.
  • headers : the Voice Application request headers as a Hash.
  • httpMethod : the method used to make the Voice Application request - either GET or POST.
  • parameters : the Voice Application request parameters as a Hash.
  • path : contains the request path to the block being run, within the application - i.e. / followed by the block name.
  • pathParameters : an empty object provided as backward compatibility.
  • queryStringParameters : the same as parameters, provided as backward.
  • requestContext : an empty object provided as backward compatibility.
  • stageVariables : an empty object provided as backward compatibility.
  • context : an empty object provided for backward compatibility.

The handler method is expected to return a string that will be parsed as the CXML response document.

Example Code​

def handler(ev, ctx)
  "<?xml version=\"1.0\"?>
  <Response>
    <Say>
      You are about to be connected to a sales representative,
      please hold on the line
    </Say>
  </Response>"
end