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
andANSWER
) 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. |