Courseware:IT Plus - Virtual interfaces

Everything you always wanted to know

Introduction

We have a new start config for this book. Please load the start configuration of this lesson to your devices. Please also update the start configuration of the app services located on the AP.

This book is a practical example of a customer scenario. In this book we will be using the routing table. If you have trouble keeping up please read the Routing Engine Theory (optional) ). This book is designed to give you the theoretical background for the upcoming exercise.

Scenario description

Due to limited bandwidth, the SIP provider allows only three concurrent calls. One channel must always remain available for incoming calls, which means only two outgoing calls are permitted at any time. If a third outgoing call is attempted, the caller will hear a message indicating that no channels are available. However, emergency calls should always be allowed—even when all channels are in use. In such cases, the emergency call should automatically disconnect one of the current calls to free up a channel.

As the final step in our preparation, please set up a SIP trunk using the Trunk Settings plugin as we did in the previous book.

Create a new trunk in the Trunks plugin of the Settings App with these parameters:

• Name and SIP: trunk

• Number: 0
  
  
• interface/SBC: hq.dvl-ckl2.net

• Default SIP Trunk

• Country Code: +49

• Connection type: DDI
• International number: +496213428231

• Lowest extension: 0

• Number mappings:

+4962134282310 -> 0

+4962134282311 -> 10

+4962134282312 -> 12

+4962134282313 -> 13

+4962134282314 -> 14

• User: DDI49.621.3428231
• Password: pw123

• Protocol: TCP
• Domain: siptrunk.class.local
• Proxy: <leave empty>
• Media Relay: on

 

Call limitation

In order to accomplish our task, we must first discuss how to limit calls to and from the provider. So, here's the deal: we are going to use Call Counter.

Call Counter

Call counters set the maximum number of calls that can pass through a map in the routing engine. Each call that passes through increases the call counter by one. As soon as the maximum value is reached, no further calls are allowed through this map. The maximum value is a configurable setting next to the call counter. The call is declined with the cause code "No circuit/channel available." This triggers a  reroute in the routing engine. Consequently, the call is forwarded to the next map in the route.

As mentioned in the scenario description, we would like to limit outgoing calls to the provider to two. The Trunks plugin creates an outgoing route with multiple maps that convert the CGPN to an international format.

Since the call counter should apply to all outgoing calls, regardless of who is making the call, we will need to add the same  Call counter named count to each map with the destination SIP1 and set the max value to 2.

To test this behavior call 00900 12345678 from John Doe, Richard Roe and afterwards Jane Doe. The third call should fail.

Well done! But what about incoming calls?

We want incoming calls to count toward the same call counter. If there are two inbound calls, no outgoing call should be allowed, since one channel must always remain available for incoming calls. The call counter can have a different max value for incoming calls. In our scenario, allowing three instead of two.

In the map of the inbound direction, please set the Call counter named count to a  maximum value of 3.

Maps can share the same call counter (count in our example). However, different limits can be imposed on the same counter in different maps.

To test it please call 00900 12345678 from John Doe and Richard Roe so both hear the announcement. Afterwards call 062134282312 from your IP232. The call to Jane is still possible. If you set the counter to 2, the call will fail.

Announcements

The next step is to implement a mechanism that plays an announcement when both outgoing channels are busy. As mentioned earlier, a disconnected call with the cause code "No circuit/channel available" will be rerouted to the next map. Unfortunately, there is no other map at the moment, so the call is released.

Before we discuss the solution, you should know that an announcement file is already present in your Files app. Your Files app contains a shared folder called announcement. In this folder, you will find audio files for different coders.

The HTTP interface

The HTTP interface (or Webmedia interface) acts as a gateway between HTTP and VoIP. It retrieves a file from an HTTP server and sends the audio data using RTP. Note that the HTTP interface does not convert the audio data. For instance, if G.711A is negotiated as the codec with the other VoIP endpoint, the HTTP interface must read the G.711A audio data from the file on the HTTP server.

While no special configuration is required to use the HTTP interface, several PBX components implicitly use it. Essentially, the HTTP interface is used every time the PBX plays an audio file retrieved via HTTP. Keep this in mind when configuring the following components:

• Music on Hold
• Waiting Queue
• Voicemail
• Conference object
• Boolean

To solve our requirement, we are going to configure a waiting queue object using the Waiting Queues plugin of the Settings App, as we learned  in the IT Connect training and set the following options for the Waiting Queue:

• Waiting queue: No free channel
• SIP: no-free-channel
• Number: leave-empty
• Announcements/Announcement 1: select no-free-channel
• Settings/Time to announcement: 0

How is the failing call routed to the Waiting Queue object?

If a call is disconnected due to a lack of channels and no further map exists, the disconnect is forwarded to the PBX, specifically to the trunk object. If a CFNR is configured on the trunk object, the call is routed to the CFNR's destination.

This means that we have to  configure a CFNR on the trunk object towards no-free-channel.

To test if our configuration is working please call 00900 12345678 from John Doe, Richard Roe and afterwards Jane Doe. Jane Doe will hear the announcement that two free channels are available.

URL Parameter

As you saw in the last chapter,  the Waiting Queue plugin creates an announcement URL like this:

https://apps-dvl-ckl2.training.innovaphone.com/dvl-ckl2.net/files/UI/announcement/no-free-channel.$coder?coder=g723,g729,opus-nb,opus-wb,g711a,g711u,g722&fileskey=5TtwrIIQFGmNdP18

This URL contains a lot of information, so we should break it down and possibly improve upon it.

• apps-dvl-ckl2.training.innovaphone.com: the fully qualified domain name of your AP.
• dvl-ckl2.net: the domain name of your files instance
• files: the name of the files instance
• UI: the location inside the files app
• announcement: the folder name inside the files instance
• no-free-channel: the name of the audio file(without a file extension)
• $coder: This is a placeholder for the negotiated coder. In case the calling endpoint uses g711a, following filename will be used:no-free-channel.g711a
• ?: This is a separating character. It divides the path to the file from additional URL parameters.
• coder=g723,g729,opus-nb,opus-wb,g711a,g711u,g722: This lists all proposed codecs. If you delete g711a from this list, g711a will not be offered to the calling endpoint. If no matching codec is found the call will be terminated.
• &: This is a separating character. It divides different URL parameters. Each time you add a new parameter you have to separate the previous parameter with an &.
• fileskey=5TtwrIIQFGmNdP18: In order to protect unauthorized access to the files app, a unique fileskey has to be know from the client(in this case the http interface). You can find this fileskey by clicking  the i button in the shared folder in the files app.

Playback Options

Add the repeat=true option to force the HTTP Interface to start playing the audio file again once it has ended. This will cause the audio file to loop indefinitely. Alternatively, you can set the repeat parameter to a number. For example, if you configure repeat=3, the announcement will stop after playing four times.

 Please add the the parameter &repeat=1 to the announcement, to loop the announcement a second time.

MoH and TONE

Two pseudo URLs are available that can be used instead of complete URLs.  While MOH will play the built-in music on hold,  TONE will play a constant tone. Both MOH and the tones played via the TONE interface are looped endlessly. Playing tones can be useful if you want to make it seem like there is a dialing, busy or ringback tone. You can add the parameter tone=[tone specification], to the pseudo URL. You can use either of this tones:

ringback - The ringback tone is played (alerting on the called site)

busy - The busy tone is played

dialing - A dialtone is played (this option is default if only TONE without parameters is used)

 Please add MOH as 2nd announcement. As soon as the first announcement ends, the caller will hear the builtin music on hold indefinitely.

Any announcement configured as the 2nd announcement will play indefinitely until the call ends. This applies to both MOH and announcement files from a WebDAV server. It will repeat even if you configure a specific repeat amount.

User to User Information

We previously discussed the concept of how an announcement is played, but didn't go into detail. Now, let's discuss how the HTTP interface knows which file to retrieve and where to find it. The answer is that the URL (the announcement URL configured previously) is provided in the H.323 call signaling by a user-to-user information information element.

1. Due to the rerouting mechanism we implemented before the call is sent to the Waiting Queue object.
2. The Waiting Queue adds the announcement URL, we configured in the last step, to the User to User information(UUI).
3. This information is sent via H.323 call signaling to the HTTP interface.
4. The HTTP interface uses this URL from the UUI to send its HTTP GET request.
5. The HTTP server (or in our case the file instance) starts to transmit the file no-free-channel.g711a to the HTTP interface.
6. The HTTP interface transfers the data from the file into RTP packets and sends it to the endpoint.

While reading the book you may have wondered why we did not reroute the call  to the HTTP interface as the next map in the routing table?

True, we could have done that. We could have even  used the add UUI option inside the map to tell the HTTP interface where to retrieve the audio file from. However, the waiting queue objects give us much more flexibility and options, making this a much better solution.

Offloading announcements to another gateway

Sometimes, it makes sense to offload the HTTP interface to another device. This means that instead of using the HTTP interface of your PBX, you would use the HTTP interface of another gateway to play MoH, WQ announcements, etc. Offloading the HTTP interface is primarily done for performance reasons. This may be necessary in scenarios with a large number of endpoints that could connect to the MoH or a waiting queue simultaneously. The simplest check is to look at the CPU-R counter on the gateway running the PBX. It can be found on Maintenance / Diagnostics / Counter in the advanced UI. The CPU-R counter shows how many CPU cycles are reserved for call processing on the PBX. If your gateway is frequently overloaded, using an HTTP interface from another gateway might help.

To configure offloading for a waiting queue object, open the object in the Advanced UI. Instead of using the local HTTP interface,  you can configure Extern Name/No to point to a gateway object in the PBX. The external HTTP interface should be registered on this gateway object. In fact you can register multiple HTTP interfaces to this object to distribute the calls in a round robin fashion.

Music on hold can be offloaded as well. Therefore, you  have to configure External Music On Hold configuration option on PBX / Config / General. You can define the name of the gateway object registered to the HTTP interface. When music on hold is played, a call is executed via this gateway object to the external HTTP interface.

Emergency calls

In case of an emergency, it is of utmost importance that at least one external call (e.g. to the police or the fire department) can be done. This should be possible even though all available channels on a trunk are currently in use.

In addition, alerting users may be stressed and confused and therefore forget to dial the normal outside line access. In other words, it should be sufficient to dial 112 instead of the correct 0112.

As a first step to allow an emergency call when all channels are busy, we need to ensure that calls to the emergency number can be made without dialing the external trunk line number. In other words, when a user like John Doe dials 112, they should be connected to the fire department without having to dial a zero for the trunk line.

We will create a number map object in the PBX with the number 112. The destination of this number map must be 0112. This way, users do not have to think about the external line prefix because the number map object takes care of it, and the external line zero is prefixed anyway.

To do this, go to your PBX's object list and  select Number Map from the drop-down menu to create such an object. Then

• Set the Long Name to Fire Brigade
• Set the Name (SIP) to fire-brigade
• Assign this object the number 112
• Put the object in the root node and location hq
•  Set the Dest. No option (Mappings tab) to 0112

To test our configuration please dial 112 from John Doe. You will hear the fire brigade announcement.

Emergency flag

To prioritize calls over existing ones we can use the Emergency flag.  This flag is a configuration option available in each map of your routing table. If a call is routed through a map with an active Emergency flag and there are no available channels, the call will not be disconnected. Instead, an existing call routed to the same destination (e.g SIP1) will be disconnected. This means the call passing through the map with the active Emergency flag is kept alive and forwarded to its destination.

In order to configure it, we will create a new outgoing map for CDPN 112 to the destination interface SIP1. This map must be the first one for the SIP1 interface because the routing table is always processed from top to bottom.

So let's try it and  create a new map before our map to SIP.

• Set the CDPN-In and CDPN-Out to 112
• Set the destination interface to your SIP trunk (probably SIP1)
• Set the Force Enblock and Emergency option for this map.

To test it please call 00900 12345678 from Jane Doe and Richard Roe so both hear the announcement.

At this point a third outgoing call is still possible as no call counter restricts this map. However, since we want to test the emergency flag, we need a third call. This must be an inbound call, as no more outbound calls can be made. To proceed, start your softphone in your myApps client and make an inbound call from your IP232 to 062134282311.Your softphone will ring—please answer the call.

Afterwards, place a call to 112 from John Doe. The longest active call that passes through the SIP interface will be disconnected.

Voilà! This is exactly what we are trying to achieve.

The emergency flag feature can also be used with Verify CGPN to prioritize calls from the boss over those from employees, ensuring they always have access to the PSTN line.

Emergency Calls and SIP Trunk

It is possible to add a location code to the called party number. Providers can use this information to identify the origin of a call, which can then be used to notify emergency services.

Several countries have implemented a scheme where, for emergency calls (e.g. 112), a location-specific prefix must be dialed before the number. This allows the provider to route the call to the emergency center nearest the caller. However, this prefix is usually not numeric; it typically starts with a capital letter E, followed by a numeric code. Thus, a call to 112 may be carried out as a call to destination E2147112, where E2147 is the location code.

You can create such a called number using the Name Out property in a route, as described in   Gateway/Routes/Map. Create a map that matches the CDPN 112 and maps it to the called name E2147°. This removes the called party number from the call and adds a called party name, replacing the ° with the original called party number.

This number is then used to create the called party URI (something like E2147112@sample.provider.tld) when interworked to SIP. It is sent as called name when interworked to H.323 or QSIG.