Navigation :

N2IVR (VXML) EDRs

N2IVR (VXML) Application EDRs

The N2IVR solution supports several different control channels, including the ability to perform interaction under control of an VoiceXML script.

In this mode, the N2IVR VXML 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.

N2IVR VXML EDRs are written to the the EDR stream vxmlivr EDR files.

The VXML IVR EDR Event Types are:

SETUP-ERR
VXML
VXML-CDR

In addition, the N2IVR under VXML-control will also generate:

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 IVR 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 IVR.
`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.

VXML EDR

The 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 IVR call, one or more 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 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 VXML EDRs are generated when the VXML IVR 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 IVR 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 IVR will capture any associated message provided with the thrown event in this EDR field.

VXML-CDR EDR

The 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 IVR application. If this EDR is generated, then the 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 IVR 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 IVR 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 IVR 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 IVR

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 IVR.
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 IVR.
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 IVR 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 locally-mapped 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 IVR's local 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 IVR 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.