LHO EDRs

Introduction

The N2 LHO SIP App is a key component in the Lua-scripted SIP Application Services offered by N-Squared as part of the N2SIP product set. The LhoSipApp performs the SIP transaction and dialog control, under the guidance of a Lua script executing within the LogicApp.

It is built on top of the SipApp base class, and hence generates the base SIP EDRs.

In addition, the LhoSipApp logs the service logic events associated with the Lua control channel. These LHO service logic EDRs are written to the same stream as the SIP EDRs, and will be interleaved with them in the EDR files.

The LHO SIP EDR Event Types are:

These EDRs are generally associated with SIP Call Control messages being exchanged between the LhoSipApp and the LogicApp, but the correlation is not exactly one-to-one.

Common Format

The configuration 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.

SHUTDOWN EDR

The SHUTDOWN EDR Event indicates that a LHO SIP call instance ended with an internal processing error. This EDR is generated independently of any other SIP EDRs associated with the call. In most cases, there will be other SIP EDRs associated with this instance containing additional protocol information.

Example:

2021-10-15 03:52:43.117<LHO-1634269880-2b8081b1>SHUTDOWN
|EXCEPTION=Timeout waiting for SUSPENDING_ALEG in SCC state SUSPENDING_ALEG.

Field Type Description
EXCEPTION String [Required] Description of the reason for the unexpected instance shutdown.

ABANDON EDR

The ABANDON EDR Event is generated when the caller hangs up the phone at any point except during “talk-time”.

Specifically, the following scenarios should generate an ABANDON EDR.

The following scenarios should not generate an ABANDON EDR.

Example:

2021-10-18 02:35:30.696<LHO-1634523782-2862ec17>ABANDON|DURING=Announcement

Field Type Description
DURING Announcement / Logic / Termination Additional information indicating the stage of processing at the time the caller abandoned the call.
Announcement - The caller abandoned while an interaction was in setup/progress.
Logic - The caller abandoned while our service logic was executing.

DECLINE EDR

The DECLINE EDR Event indicates that the service logic has requested the call be declined via a SIP response code in the range 300-699. This may optionally include an updated Contact header, and/or a Reason header.

Example:

2021-10-18 02:34:58.201<LHO-1634523782-2862ec06>DECLINE|CODE=302|REDIRECT=145646600000023

Field Type Description
CODE Integer The SIP Result code used to decline the call, between 300 - 699.
REDIRECT String The address digits used to from the Contact header value (if present).
REASON String The value of the Reason header (if present).

HANGUP EDR

The HANGUP EDR Event indicates that the service logic has requested the call be terminated cleanly. On-the-wire messaging could involve a final response, BYE, or CANCEL depending on the SIP transaction and dialog state.

Example:

2021-10-18 02:34:58.201<LHO-1634523782-2862ec06>HANGUP|CODE=603

Field Type Description
SOURCE Service [Required] The originator of the instruction to end this call. The value is fixed.
CODE Integer The SIP Result code used to decline the call (if applicable)
If present this value will be between 300 - 699.
REASON String The value of the Reason header (if present).

OUTCALL EDR

The OUTCALL EDR Event indicates that the service logic has requested that the N2SIP stack initiate a new standalone A-Leg.

Example:

2021-10-18 02:35:22.935<LHO-1634523782-2862ec12>OUTCALL
|ADDRESS_DIGITS=6483330000|CLI=642220101|NOANSWER=15

Field Type Description
ADDRESS_DIGITS String [Required] The address digits specified by the service logic for the new A-Leg.
These will pass through normalisation, trunk selection, and the other features of the SIP stack.
CLI String [Required] The calling line identification for the new A-Leg.
These will pass through normalisation, trunk selection, and the other features of the SIP stack.
NOANSWER Integer [Required] The maximum ring-time, after which the call will be considered "No-Answer" if it did not successfully reach the A-Party.

TERMINATION EDR

The TERMINATION EDR Event indicates that the service logic has requested that the N2SIP stack acts a Back-to-Back User Agent to connect an existing A-Leg to a new B-Leg.

That is:

Note that this EDR is not applicable for ETC (establish temporary connection) legs to an external or internal media server.

Example:

2021-10-18 02:35:22.935<LHO-1634523782-2862ec12>TERMINATION
|ADDRESS_DIGITS=6483330000|CLI=642220101|NOANSWER=30|MAX_TALK=7200

Field Type Description
ADDRESS_DIGITS String [Required] The address digits specified by the service logic for the new B-Leg.
These will pass through normalisation, trunk selection, and the other features of the SIP stack.
CLI String [Required] The calling line identification for the B-Leg.
These will pass through normalisation, trunk selection, and the other features of the SIP stack.
NOANSWER Integer [Required] The maximum ring-time, after which the call will be considered "No-Answer" if it did not successfully reach the B-Party.
MAX_TALK Integer [Required] The maximum talk-time, after which the A-Leg/B-Leg talk path will be torn-down.
MONITORED 1 When present and 1 indicates that the service logic requested monitor reporting for this call.
(Default = service logic did not monitor this call).
CHARGED 1 When present and 1 indicates that the service logic requested grant-based charging control for this call.
(Default = service logic did not control grants for this call).

ANSWER EDR

The ANSWER EDR Event indicates that the current attempt to join (via signalling only) two external call legs (as per the preceeding TERMINATION) was successful. This EDR is generated both when we accept the inbound INVITE request by sending a 2XX response code, and also when we use re-INVITE to connect a new B-Leg to the existing A-Leg.

Example:

2021-10-18 02:23:19.209<LHO-1634523782-2862ebba>ANSWER|FINAL=1

Field Type Description
LEG A / B Indicates if this EDR relates to the INVITE for an A-Leg (Outcall) or a B-Leg (Termination).
FINAL 1 This field is present if and only if this represents the end of service logic call control.
ONGOING 1 This field is present if and only if the call is still under service logic control.
MONITORED 1 This field is present if and only if the call is still under service logic control for monitoring.
CHARGED 1 This field is present if and only if the call is still under service logic control for charging.

The “Answer” time is the time at which the leg setup is is confirmed, according to the SIP INVITE state model.

Note that there is the potential for the A-Leg to deliberately delay or not send acknowledgement of the SIP 200 OK which we send. This would delay the Answer timestamp, and hence would fraudulently reduce the wall-clock talk-time measured between the Answer and the BYE for the purpose of computing the TALK_DSM timestamp in the TERMINATION EDR.

TEARDOWN EDR

The TEARDOWN EDR Event indicates that either:

Examples:

2021-10-18 02:35:26.351<LHO-1634523782-2862ec12>TEARDOWN|REASON=B-Leg BYE|TALK_DSM=14

2021-10-18 02:43:40.508<LHO-1634525008-751a5aa6>TEARDOWN|CODE=486|REASON=Declined

2021-10-18 02:44:00.137<LHO-1634525008-751a5ab2>TEARDOWN|REASON=No Route

Field Type Description
CODE Integer The SIP Response code (if applicable) in the range 300 - 699 which the far-end used to decline the attempt to set-up this voice talk segment.
FINAL 1 This field is present if and only if this represents the end of the call control.
i.e. if no follow-on call is possible because both legs of the call were torn down using BYE.
ONGOING 1 This field is present if and only if the call is still under service logic control.
i.e. if only one leg was torn-down at this time.
REASON A-Leg BYE / B-Leg BYE / Abandon / Max Duration The reason for the termination of the voice talk segment.
A-Leg BYE - The A-Leg initiated call teardown with BYE.
B-Leg BYE - The A-Leg initiated call teardown with BYE.
Abandon - The A-Leg abandoned the call during B-Leg setup.
Max Duration - The in-progress call exceed our configured hard-limit maximum duration.
A-Leg Unresponsive - The A-Leg did not respond to activity tests during monitored talk-time.
B-Leg Unresponsive - The B-Leg did not respond to activity tests during monitored talk-time.
A-Leg/B-Leg Unresponsive - Neither A-Leg nor B-Leg responded to activity test during monitored talk-time.
ACTIVITY Array of Integer This field indicates at what time (in seconds from call start) an Activity Test (empty SIP re-INVITE) was used to supervise the call, either for Monitoring, Charging, or general call supervision.
Array EDR values are comma-separated. An empty string indicates that empty SIP re-INVITE was not initated by us for the purpose of Activity Test.
TALK_DSM Integer The measured talk time determined by the SIP. The wall-clock time measured from the the Answer time, to the time at which the first BYE is received or sent.
See the comments in regards to delayed confirmation in the ANSWER EDR.
Unit = deci-seconds.

ETC EDR

The ETC EDR Event indicates that a LHO SIP call instance has opened a SIP connection to an external media server, as directed by a Lua service logic script which has specified the name of an external media server. This media server will be one of the SRF nodes defined in the <srfs> configuration.

Example:

2021-10-15 03:53:13.513<LHO-1634269880-2b8081b2>ETC
|MS_ADDRESS=9991696

Field Type Description
MS_ADDRESS String [Required] The digits of the media server destination address for the B-Leg channel setup.

CTR EDR

The “Connect to RTP” EDR Event is used in the special case where the service logic requests that the RTP channel be established back to the A-Party as a separate step, without immediately also beginning the playing of an audio stream.

This is used by the N2INVR service logic, because (depending on the controlling SCP and SSP) it may be desirable or even necessary to establish the leg back to the switch before the SCP will send the first instruction message.

Examples:

2023-11-04 05:01:19.424<kirby~IVR~1699073988~7c4e2cb3>CTR

This EDR has no fields.

PLAY EDR

The PLAY EDR Event indicates the SIP requesting to an on-switch or external media server that an announcement be played (possibly including variable part content), and that optionally a DTMF digit response be entered by the handset.

Examples:

2021-10-18 02:44:57.947<LHO-1634525008-751a5abc>PLAY|LANGUAGE=English|LANGUAGE_ID=1|MESSAGE_ID=25204|SRF=SrpSipApp

2021-10-18 02:43:36.321<LHO-1634525008-751a5aa4>PLAY|LANGUAGE=English|MESSAGE_ID=25204|SRF=

Field Type Description
CANCEL_DIGIT [*#0-9A-F] The Cancel Input Digit used for the interaction (if any).
Present only if this is a prompt-and-collect interaction.
Note that the SCP may in theory specify E and F for this value, although these are not valid digits for INAP-compatible DTMF detection according to CCITT specifications Q.23 [7] and Q.24.
DURATION Integer (Seconds) This field is present if and only if the service specified a maximum duration for the interaction.
This field is present only for external interactions sent using PA/PACUI, where it is the duration attribute.
END_DIGIT [*#0-9A-F] The End of Input Digit used for the interaction (if any).
Present only if this is a prompt-and-collect interaction.
Note that the SCP may in theory specify E and F for this value, although these are not valid digits for INAP-compatible DTMF collection according to CCITT specifications Q.23 [7] and Q.24.
FIRST_DTO Integer (Seconds) This field is present if and only if the interaction was a prompt, and the service specified a first digit time-out.
For internal elements this is sent in the RTP-PLAY announcement object.
For external announcements, contains the value sent via firstDigitTimeOut in PA/PACUI.
INTER_DTO Integer (Seconds) This field is present if and only if the interaction was a prompt, and the service specified an inter digit time-out.
For internal elements this is sent in the RTP-PLAY announcement object.
For external announcements, contains the value sent via interDigitTimeOut in PA/PACUI.
INTERRUPTABLE Integer This field is present if and only if the interaction was a prompt, and the service specified that the prompt be interruptable.
For internal elements this is sent in the RTP-PLAY announcement object.
For external interactions sent using PA/PACUI, this is the interruptable attribute.
INTERVAL Integer (Seconds) This field is present if and only if the service specified an interval for the interaction.
This field is present only for external interactions sent using PA/PACUI, where it is the interval attribute.
LANGUAGE String This is the name of the language explicitly requested by the service logic.
This field will not be present if the service logic did not specify a language.
LANGUAGE_ID Integer This is the integer language ID sent to an external media server using an INAP integer language ID extension.
This field is not present for internal announcements.
This field will not be present if the service logic did not specify a language.
MAX_DIGITS Integer This field is present if and only if the interaction was a prompt.
For internal elements this is sent in the RTP-PLAY announcement object.
For external announcements, contains the value sent via maximumNbOfDigits in PA/PACUI.
MESSAGE_ID Integer The elementaryMessageID in the case where only one message ID is requested.
Either MESSAGE_ID or MESSAGE_IDS must be present.
MESSAGE_IDS Integer List The elementaryMessageIDs in the case where more than one message ID is requested.
This is a comma-separated list in the EDR.
MIN_DIGITS Integer This field is present if and only if the interaction was a prompt.
For internal elements this is sent in the RTP-PLAY announcement object.
For external announcements, contains the value sent via minimumNbOfDigits in PA/PACUI.
COLLECT 1 This field is present if and only if user DTMF input was requested.
REPETITION Integer (Seconds) This field is present if and only if the service specified a number of repetitions for the interaction.
This field is present only for external interactions sent using PA/PACUI, where it is the numberOfRepetitions attribute.
SRF String [Required] The name of the SRF that will be engaged to perform the interaction.
An empty value in this fields indicates that an internal media server was used.

PLAYED EDR

The PLAYED EDR Event indicates that the on-switch or external media server has completed playing an announcement (possibly including variable part content), and that optionally a DTMF digit response has been entered by the handset.

There should always be a 1:1 correspondence between PLAYED and PLAY EDR Events, and so a missing announcement, or a mid-announcement hangup/abandon will generate PLAYED EDR Events with an ERROR field (rather than PROBLEM EDR Events).

Example:

2021-10-18 00:40:04.319<LHO-1634517525-21511760>PLAYED|

Field Type Description
DIGITS String The returned digits if DTMF entry was requested and if a sufficient number of digits was supplied by the user.
If the service or system defaults marked these digits as "private" then the digits will be replaced by the ? character in the EDR.
ERROR Integer Indicates that an error occurred during the announcement, such as the requested announcement ID(s) not being known, or the caller abandoning during the announcement.
Note that the caller not providing sufficient digits before timeout (e.g. entering 3 digits when a minimum of 4 is specified) will be recorded as `DIGITS` present but empty, and `ERROR` not present.