Action Scripts expose an api that help you interact with the telephone system.
class BaseRouteStep
When you create a new Action Script a default implementation will be created. Your Action Script will be derived from the base class 'BaseRouteStep'.
As Noojee PBX is based on Asterisk its worth understanding that calls are passed into Routing using fast agi using the Asterisk-Java library.
https://github.com/asterisk-java/asterisk-java
The main way of controlling a call is via agi commands. You can issue AGI commands by calling the getAgi() method on the BaseRouteStep class.
The base class has a number of other useful methods that make it easy to write a Route script.
Realm
Set by the Trunk through which the call entered the system. Even calls from internal extensions (handsets) enter Routes via a Trunk.
The Realm is used to determine the direction of the call. The system uses the Source realm and the Delivered To realm to determine the direction of the call. The systems ability to determine a calls direction is important when determining whether a call should be recorded for an Account as well as for general reporting purposes. It should be noted that superficially it would appear to be quite easy to determine a calls direction however in practices it can be quite complicated as a call can actually changed direction mid way through the call.
Target
A Target can be a phone no., a pattern or an alphabetical literal.
A Target pattern is a used to match Targets consisting of digits only.
SourceNo
Set by core routing each time a call is originated. For inbound this is the caller id, for calls dialed from a handset this is the handset extension no.
DialedNo
- called by the core routing logic when a call first enters the system. Normally this wouldn't be modified by a script unless the trunk provider provides a badly formatted no. hin which you may want to re-reformat it using the rewrite action.
For most systems the dialed no. doesn't change during the life of a call.
setCurrentTarget(target)
Called by the core routing logic whenever a call matches a route target including when the call enters the very first route.
The routed no is essentially updated each time the call transition into a new route Target (the Gosub step is the main method of changing the current Target).
The BaseScriptRoute class exposes the following methods.
Overview:
| Method | Arguments | Return type | Comments |
|---|---|---|---|
| dial | Trunk trunk, String phoneNo, String options, int timeout | void | Dials the given phone number using the selected trunk. trunk - the trunk to dial over phoneNo - the phone number to dial options - any asterisk dial options required. timeout - the time (in seconds) to wait for the dial to connect. |
| conference | String roomNo, String pin, String options | roomNo - The conference room to pass the call to. If the conference room doesn't exist it will be dynamically created. PIN - the pin number used to control access to the conference room. Pass a blank string if you don't want a PIN assigned to the conference room. options - any valid asterisk conference room options. | |
| getAccountFromId | Long id | Account | Look up an account using the id passed in. The Account object returned is detached from the database. |
| getAgi | void | BaseAgiScript | Returns the BaseAgiScript, this allows direct agi calls to be made against the channel |
| getArgAsBoolean | String fieldName | Boolean | Takes a fieldName for the Script and returns the fields value as a Boolean. |
| getArgAsInt | String fieldName | Integer | Takes a fieldName for the Script and returns the fields value as an Integer. |
| getArgAsLong | String fieldName | Long | Takes a fieldName for the Script and returns the fields value as a Long. |
| getArgAsString | String fieldName | String | Takes a fieldName for the Script and returns the fields value as a String. |
| getBMMFileNameFromId | Long id | String | Returns the name of the BMM audio file without the file extension. This is suitable for passing to the 'playback' command which assumes the file doesn't has a file extensions. |
| getChannelVariable | String name | String | Gets the value of an Asterisk channel variable. |
| getDialedNo | Void | String | Returns the number that was dialed to trigger this call route. For inbound calls this will be the DID, for outbound calls it will by the number dialed from the handsets. |
| getDirection | Void | au.com.noojee.callrouting.CallDirection | Returns the CallDirection enum indicating which direction the call is flowing in. CallDirection has the following possible values: CallDirection.INBOUND CallDirection.PASS_THRU - not used on most systems CallDirection.INBOUND |
| getHandsetFromId | Long id | Handset | Looks up the Handset indentified by id and returns a detached entity |
| getPhoneNoForAccountId | Long id | String | Returns the phone currently attached to the given account. |
| getQueueFromId | Long id | Queue | Looks up the Queue indentified by id and returns a detached entity |
| getRoutedNo | None | String | The current RoutedNo. See setRoutedNo() for details. |
| getSourceNo | None | String | Returns the source phone no. that originated the call. For an inbound call it is the callers caller id, for an outbound call it is the handsets extension no. |
| getSourceRealm | None | Realm | Returns the Realm for the current call. When any call enters the system a Realm is set to describe how the call entered the system. The two Realms are Realm.INTERNAL and Realm.EXTERNAL |
| getSystemVariable | String key | SystemEntity | returns a detatched system variable entity for the given key. |
| getTrunkDialStringFromId | Long id | String | Returns the Dial String for the trunk whose primary key is id. |
| getTrunkFromId | Long id | Trunk | Returns the Trunk object whose primary key is id. |
| getVariable | String name | String | Gets the value of the Route Script variable with the given name. Route Script Variables have a life cycle linked to the underlying call. Route Script Variables are much faster than Channel Variables. |
| getVoiceMailBoxFromId | Long | VoiceMailBox | returns the VoiceMailBox entity for the given id. |
| gosub | RouteContext context, String target | void | Send the call to the given context with the given target as the 'deliveredTo' number. |
| queue | Queue queue, String options, int timeout | void | queuename - the name of the queue to send the call to options - any valid asterisk queue options timeout - the amount of time to wait for the call to be connected before exiting the queue. The deliveredTo number gets set to the Agents extension when the call is answered by an agent. |
| setChannelVariable | String name, String value | Void | Sets the value of an Asterisk channel variable. |
| setDialedNo | String number | Void | Allows the dialedNo to be modified by a script. |
| setSource | String number, Realm realm | Void | Set the number the call came from and the realm (INTERNAL/EXTERNAL ETC) |
| setVariable | String name, String value | Void | Sets the value of the Route Script variable with the given name creating it if it doesn't already exists. |
| substituteVariables | String message | String | Parses the passed message looking for any encoded Route variable names and replacing the encode variable name with the variables value. The encoding scheme is of the form: ${variablename} |
| startRecording | boolean force, String tag | Void | Unconditionally starts recording the current call. If recording is already running then a new leg is started. |
| stopRecording | boolean force | Void | Stops recording. |
| voicemail | String vmbox, String options | void | Connects the caller to the given voicemail box. vmbox - the voicemail box no. options - any valid asterisk voicemail box options. |
| variableExists | String name | Boolean | returns true if the variable with the given name exists and is non-zero in length. |
Variables:
Routes provide a number of default system variables which can be access to determine information pertaining to the current call or the system as a whole. The following variables can be access by calling getVariableValue(variableName) on the Api.
Please note that these variables are readonly and as such you can't update them however the system may update some of them as a call progresses through a route.
| Variable Name | Description | Scope |
|---|---|---|
| nj.DeliveredTo | When a call is initially routed or Gosub is called the value in nj.Target is used to pattern match against possible targets in the context. When a specific target is selected 'nj.DeliveredTo' is set to the value of the Target that matches. e.g. nj.Target might be: 03 8320 8100 but nj.DeliveredTo might be 03 XXXX XXXX. | Gosub |
| nj.DialedNo | The number that was dialed to cause the current call. For an inbound call this will be the DID for an outbound call this will be the no. dialed from the staff members handset. The dialed no. will not change over the life of a call. | Call |
| nj.Realm | Set by the Trunk through which the call entered the system. Even calls from internal extensions (handsets) enter Routes via a Trunk. The Realm is used to determine the direction of the call. The system uses the Source realm and the Delivered To realm to determine the direction of the call. The systems ability to determine a calls direction is important when determining whether a call should be recorded for an Account as well as for general reporting purposes. It should be noted that superficially it would appear to be quite easy to determine a calls direction however in practices it can be quite complicated as a call can actually changed direction mid way through the call. Realms are INTERNAL,EXTERNAL | Call |
| nj.Direction | INTERNAL,OUTBOUND,PASS_THRU,INBOUND | |
| nj.SourceNo | Set by the core routing each time a call is originated. For inbound calls this is the caller id, for calls dialed from a handset this is the handset extension no. | Call |
| nj.Target | The target typically starts out with the same value as the 'nj.DialedNo' but unlike nj.DialedNo the variable nj.Target is updated each time the Gosub command is called. nj.Target is updated to match the second argument of the Gosub command (context, target). When a Gosub returns it will reset the nj.Target variable to the value it was before Gosub was called. | Gosub |