N2SRP (VXML) EDRs

N2SRP (VXML) Application EDRs

The VoiceXML controlled N2SRP engine interprets VoiceXML documents served by a HTTP server and executes the VXML logic using the N2SVCD Lua interpreter framework. It is built on top of the SipApp base class, generating both the the base SIP EDRs, as well as its own EDRs. SRP EDRs are written to the the EDR stream vxmlsrp EDR files.

The VXML SRP EDR Event Types are:

Common Format

The parameters for configuring EDR output including filename structure and location is defined in the configuration documentation for the EdrApp which is a base component provided by the n2svcd package. All EDRs are written by the EdrApp application using its file and record formatting rules. Refer to the n2svcd base documentation for more details on configuring and managing EDR streams, and on the syntax/encoding details for N-Squared EDRs.

SETUP-ERR EDR

SETUP-ERR EDRs are generated in all error cases where a call is ended before the first VoiceXML document of the session is interpreted by the SRP VXML interpreter. This includes when a successful HTTP response to the initial HTTP request for a VoiceXML document is made, but the response does not include a valid or supported VoiceXML document.

Field Type Description
CALL_ID String [Required] The Call ID of the SIP controlled call.
CALLED String [Required] This is the called party from the SIP INVITE (i.e. from the To header).
CALLING String [Required] This is the calling party from the SIP INVITE (i.e. from the From header).
CODE Integer [Required] The reason code for the failure. Each failure pathway is captured by a unique failure code. See Error Codes below for a list of the codes that may be generated by the VXML SRP.
FORCE_HANGUP Integer (0 / 1) [Required] If set to 0, the caller was not on the line at hangup. If 1, the caller was considered connected and a forced hangup of the calling party was required.
REASON String [Required] The reason why the call setup failed. This is a descriptive message on the failure cause.
VXML_SOURCE String [Optional] If setup failed during or after retrieving the first VoiceXML document, the VXML_SOURCE field of the EDR will provide the URI/Path queried for the VoiceXML document.

SRP-VXML EDR

The SRP-VXML EDR captures the processing for a voice call during the interpretation of a VoiceXML document. When the VoiceXML intepreter successfully transitions to a new document, a new EDR will be generated for the previous document’s full intepretation. For a normal VXML SRP call, one or more SRP-VXML EDRs will be generated.

Note that if the VoiceXML intepreter fails to transition to a new document when requested, then the previous document’s processing will continue (a SRP-VXML EDR will not be generated at that time).

Note that if the first VoiceXML document cannot be interpreted a SETUP-ERR EDR is generated instead.

Note that SRP-VXML EDRs are generated when the VXML SRP configuration option MERGE_EDRS is false.

Field Type Description
ACTIONS String [Required] A comma-separated list of actions that the VoiceXML interpreter took during the interpretation of the VoiceXML document processed.

See ACTION Value Format for a list of the different actions that can be encoded in this field.

AUDIO String [Optional] A comma-separated list of the audio files or audio file message IDs that are played back to the caller. This list also interweaves input flags to identify digits input by the caller.

This may be empty if during the processing of the given VoiceXML document no audio is played.

See AUDIO Value Format for the format of this field.

CALL_ID String [Required] The Call ID of the SIP controlled call. Multiple EDRs for the same call will have the same CALL_ID.
CALLED String [Optional] Only generated for the first EDR in a call (i.e. one where IDX=1. This is the called party from the SIP INVITE (i.e. from the To header).
CALLING String [Optional] Only generated for the first EDR in a call (i.e. one where IDX=1. This is the calling party from the SIP INVITE (i.e. from the From header).
FORCE_HANGUP Integer (0 / 1) [Optional] If set to 0, the caller was not on the line at the end of call processing. E.g. because they hung up, or because the VXML document executed a <disconnect> action. If 1, the caller was considered connected and a forced hangup of the calling party was required. This field is only included in the last EDR in the call EDR sequence.
IDX Integer [Required] An ordering field. The first EDR generated will have IDX=1. and each EDR after the first will have the IDX incremented by 1.
EVENT String [Optional] If a VXML event was triggered and not handled by the intepreted VXML document, the VXML SRP will capture the event in this EDR field.
MESSAGE String [Optional] If a VXML event was triggered and not handled by the intepreted VXML document, the VXML SRP will capture any associated message provided with the thrown event in this EDR field.

SRP-VXML-CDR EDR

The SRP-VXML-CDR EDR captures the processing for a voice call across all interpreted VoiceXML documents. This type of EDR is only generated if the MERGE_EDRS configuration option is set for the SRP application. If this EDR is generated, then the SRP-VXML EDRs are not generated.

Note that if the first VoiceXML document cannot be interpreted a SETUP-ERR EDR is generated instead.

Field Type Description
ACTIONS String [Required] A comma-separated list of actions that the VoiceXML interpreter took during the interpretation of the VoiceXML documents processed during the call.

See ACTION Value Format for a list of the different actions that can be encoded in this field.

AUDIO String [Optional] A comma-separated list of the audio files or audio file message IDs that are played back to the caller. This list also interweaves input flags to identify digits input by the caller.

This may be empty if during the processing of the VoiceXMLs document for the call requested no audio played.

See AUDIO Value Format for the format of this field.

CALL_ID String [Required] The Call ID of the SIP controlled call. All EDRs for the same call will have the same CALL_ID.
CALLED String [Required] This is the called party from the SIP INVITE (i.e. from the To header).
CALLING String [Required] This is the calling party from the SIP INVITE (i.e. from the From header).
FORCE_HANGUP Integer (0 / 1) [Required] If set to 0, the caller was not on the line at the end of call processing. If 1, the caller was considered connected and a forced hangup of the calling party was required.
EVENT String [Optional] If a VXML event was triggered and not handled by the intepreted VXML document, the VXML SRP will capture the event in this EDR field.
MESSAGE String [Optional] If a VXML event was triggered and not handled by the intepreted VXML document, the VXML SRP will capture any associated message provided with the thrown event in this EDR field.

VXML-REST-REQ EDR

The VXML-REST-REQ EDR captures each request to retrieve a VXML document from a HTTP endpoint during call processing. As the interpretation of a VXML document may make multiple HTTP requests (e.g. a HTTP request failure will not stop the interpretation of the current VXML document) REST requests made during the SRP VXML handling of a call will each get their own EDR.

This EDR type is generated whether MERGE_EDRS is set to true or false.

Field Type Description
CALL_ID String [Required] The Call ID of the SIP controlled call. All EDRs for the same call will have the same CALL_ID.
VXML_SOURCE String [Optional] The HTTP URI of the VXML document requested, including any query args.
CODE Integer [Required] Will be set to `2000` when a successful HTTP request is made and the response received. Will be set to a `5xxx` error code on failure. See Error Codes below for a list of the codes that might be encounterd.
HTTP_CODE Integer [Optional] The HTTP response code, if one is received.
LUA_LENGTH Integer [Optional] The length of the Lua transpiled code block representing the VXML document received.
TIME_S Decimal [Required] The lengh of time, in seconds, waited by the VXML interpreter for receiving the VXML document via HTTP. This is calculated from the Lua, so include IPC and other N2SVCD app processing times to make the request, and process the result. It also includes the transpilation time of transpiling the VXML into Lua.

Extra EDR Tags

The VXML interpreter will include extra EDR tags if provided any by the interpreted document. The following elements may generate extra EDR tags in certain circumstances.

Note that extra EDR tags cannot overwrite any core tags described elsewhere in this documentation. If a user-specified EDR tag would overwrite an existing tag, the EDR tag is prefixed with X_.

EXIT Element

  • An <exit> element’s expr will be included in the final EDR for the call, in the EDR tag result. For example:
       <block>
         <exit expr="'meta-done'"/>
       </block>

will generate the EDR tag/value result=meta-done

  • Any variables from the VXML interpreter included in the namelist of the <exit> element will be included in the EDR, with the variable name as the EDR tag, and the variable value as the EDR tag value.

DISCONNECT Element

  • A <disconnect> element’s namelist of variables will be included in the final EDR for the call. For example:
       <block>
           <disconnect namelist="disc01 disc02 disc03"/>
       </block>

will generate EDR tag/value pairs for disc01, disc02 and disc03.

Detailed EDR Tag Values

Error Codes

The following codes may be generated by the process of the VXML SRP

Code Reason
5000 No match in the SERVICE_IDENTIFICATION mapping for the incoming called party number. The SERVICE_IDENTIFICATION mapping, configured in the n2svcd.xml configuration file, determines the initial VXML document URL to retrieve for an inbound call request.
5001 During setup of the RTP channel with the calling party, the calling party disconnected (e.g. because the caller hung up).
5002 During setup of the RTP channel with the calling party, the SIP cal failed (e.g network failure occurred). The exact cause of the setup failure will be further described in the REASON EDR field.
5003 The VXML document could not be intepreted due to a compilation error. The compilation error will be given in the REASON field.
5004 The maximum number of transitions between VXML documents has been exceeded. The default maximum is 10, however this may be changed by setting the MAX_TRANSITIONS configuration variable for the VXML SRP.
5005 An error in interpretation of the VXML document has occurred. The exact error will be given in the REASON field. Note that a VXML error that is captured by a <throw> or during interpretation by the interpreter as an error.semantic error will not be captured as an error code. This error code is limited to unexpected intepretation errors.
5006 An internal interpreter error. An unexpected interpreter action was received.
5007 The maximum number of transitions between form fields and forms within a single VXML document has been exceeded. The default maximum is 1000, however this may be changed by setting the MAX_REENTRIES configuration variable for the VXML SRP.
5010 A n2svcd error was encountered while attempting to perform a HTTP request to retrieve the initial VXML document.
5011 A response was not received by the N2SVCD REST app.
5012 A VXML property could not be set during call setup. The REASON field will determine the error in more detail
5013 A HTTP response was received, but could not be understood by the VXML SRP engine. The REASON field will determine the detailed error.
53xx / 54xx / 5xx A 53xx, 54xx or 55xx error code represents a HTTP error in retrieving the initial VXML document to interpret. The HTTP code is the last three digits of the 5xxx error.

ACTIONS Format

The ACTIONS EDR field is a comma separate list of ordered items describing the list of actions performed by the VXML interpreter in response to the VXML document’s interpretation.

The ACTIONS list is not a 1:1 mapping of VXML <element>s. Each action however matches a processing path taken by the VXML interpreter.

Each comma-separated action is in the form ACTION[:descriptor] where :descriptor is optional and its inclusion depends on the action.

An example ACTIONS field value might be:

DLG:get_card_info,ITEM:get_card_info_formitem,THRW-noinput,DLG:get_card_info,ITEM:get_card_info_formitem,DLG:visa,ITEM:visa_formitem,THRW-noinput,DLG:visa,ITEM:visa_formitem
Action Descriptor Action Description
DISC none When the VXML <disconnect> element is encountered, the DISC action is listed in the ACTIONS list.
DLG The ID of the dialog. A VXML dialog was entered. A VXML dialog is a <form> or a <menu>.

If the dialog is given an id in the VXML documen this will be given. If the ID of the dialog is not specified in the VXML document, the internally generated ID of the dialog will be given. An internally generated ID begins with an underscore.

EXIT none If the VXML <exit> action was triggered, either explicitly by the VXML document, or implicitly.

The EXIT action will always be the last action of a call if it occurs.

GOTO none, or the dialog or form field to go to. When a <goto> is requested which results in a request for a new HTTP document, the <goto> action will have no descriptor. When a <goto> is requested to a named dialog (form/menu) or named form field item in the current scope, the descriptor will identify the target.
ITEM The name of the form item. A VXML formitem was entered. A VXML formitem is a <block>, a <field> etc.

If the form item is given an name in the VXML documen this will be given. If the name of the form item is not specified in the VXML document, the internally generated name will be given. An internally generated name begins with an underscore.

PLAY Set to true or false depending on whether DTMF digits will be expected. Playback of audio to the caller was initiated. interaction was expected if the descriptor was set to true.
SBMT none When the interpreter encounters a <submit> element, the submit action will be tracked with the SBMT value. No descriptor is given for this.
THRW The event thrown. If an event was thrown in the interpreter, either explicitly by the VXML document using the <throw> element, or implicitly - e.g. by the user not entering digits when prompted - the THRW action will capture the event thrown.
TRFR Destination Number A transfer was requested to the given destination number.

AUDIO Format

The AUDIO EDR field is a comma separate list of ordered items describing the list of audio files played, and the outcome of any prompt situation where the caller’s input was expected by the VXML interpreter.

An example of an AUDIO EDR field is:

a/3s_silence,^-,1101,1102,^-,a/3s_silence,^X

which states:

  • The 3s_silence audio file is played.
  • No input was expected. Interpretation continues
  • The message IDs 1101 and then 1102 were played
  • No input was expected. Interpretation continues
  • The 3s_silence audio file is played.
  • The VXML interpreter determined the calling party hung up during the announcement.
Value Example Description
A message ID 1000 The VXML interpreter can play SRP message IDs when an audio file with the form builtin://<message-id> is used. Any message ID requested for playback using this format of the URI in the <audio> VXML action will be listed as the message ID.
A file name a/<file> The VXML interpreter played the announcement audio file given by <file>, which will be a named file in the SRP's file list.
A variable part v/<variable part> The VXML interpreter played the variable part defined by the <variable part>. Variable part names are coded into the SRP for each language codec.
No input, and none was expected. ^- The VXML interpreter played one or more audio files to the calling party, but did not expect any DTMF digits to be received. It did not receive any.
Error during audio playback or DTMF detection. ^E The VXML interpreter encountered an error during either audio playback, or DTMF detection. Often this will be due to an audio file being missing.
Caller did not enter any DTMF digits. ^N The calling party was expected to enter one or more DTMF digits, but has not.
Caller disconnected during audio playback / DTMF detection. ^X The calling party hung up during the interaction / audio playback.
Caller entered digits. +<digits> The calling party entered digits in response to a prompt. The digits may not correspond to the required length or input format. The digits will include * and # if entered.