Navigation :

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:

SHUTDOWN
ABANDON
DECLINE
HANGUP
OUTCALL
TERMINATION
ANSWER
TEARDOWN
ETC
CTR
PLAY
PLAYED

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.

Caller hang-up while service logic is determining the next step (REASON = Logic).
Caller hang-up while the announcement path is being established, played, or torn-down (REASON = Announcement).
Caller hang-up while the B-Leg termination is being established, ringing, or torn-down (REASON = Termination).

The following scenarios should not generate an ABANDON EDR.

Service logic ends the call by using .decline, .hangup, or implicit hang-up by reaching end-of-script.
Call control is ended by a processing exception which generates a SHUTDOWN EDR.
A-Leg hang-up during talk-time.
B-Leg hang-up during talk-time for a type of termination which does not support follow-on calling.

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:

N2SIP sits between the two external legs and performs transparant SIP/SDP message proxying.
N2SIP does not transcode any RTP packets, and is not in the RTP path during the call.

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:

The current attempt to join (via signalling only) two external call legs (as per the preceeding TERMINATION) has failed. In this case, TALK_DSM is present.
The previously successful attempt to join (via signalling only) two external call legs (as per the preceeding TERMINATION and ANSWER) is now over and has been torn-down.

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.