Course13:IT Advanced - 08 More on advanced PBX object types

This book discusses the more advanced PBX object types.

Start configuration

In this course, we're using the  test mode on the General / License so you do not need real licenses. Keep in mind that the test mode expires after 8 hours and must be re-started then.

Of course, if you have valid licenses, they will do too

---

Please make sure you load the more_pbx_details_objects start configuration to your devices!

Just to be sure that all of your leases fall in to place right, power cycle your whole setup when the configuration is loaded.

Well, this actually does nothing to your device configuration. It merely switches to another testsuite (which is used in the My Devices page). Therefor, it is assumed that you did the configuration as described in the previous book. Otherwise, the exercises in this book won't work well!

The Trunk Object

The  Trunk Line object is typically used to register external interfaces (SIP trunk, ISDN, FXO) at the PBX. It therefore often represents the connection of a PBX to the PSTN. We've already configured it using the Trunks PbxManager plugin. Here are some more details.

If your outgoing calls did not work, please remember to uncheck the call filter we configured in the last book.

Manipulating the CGPN

The  Trunk allows to define the  policy for outgoing numbers (CGPN) globally.

If the Outgoing Calls restricted property is set, all outgoing calls will be sent with the CGPN suppressed (CLIR).

As an alternative, the CGPN can be set to a specific value (such as 0) for all calls by setting the Outgoing Calls CGPN property.

As with the CGPN, the calling name can be suppressed for all outgoing calls by setting the Outgoing Calls No Name property. This may be useful when a SIP trunk (or a QSIG tie line - if you don't now what that is, just don't care ) is used but is rather pointless with ISDN or FXO trunk lines (as they do not use the Name property anyway).

While we are at that: you can also tick the No Presence/Dialog Subscribe check-mark. This inhibits subscriptions through the trunk and is useful if your SIP trunk gets confused with such subscriptions (or if you use ISDN or FXO as your trunk interface will reject presence calls anyway)

Calling to the PSTN

To play around with the Trunk's number handling, we need a PSTN and access to it. Fortunately, we have prepared one

The trunk which we configured while working through the previous book is connected to a simulated PSTN. You can easily try it out by calling the fire brigade (0 112), a charged hotline (0 0900 12345678) or yourself (0 0621 3428231-1) from any of your phones.

But we can do even more: we can simulate an external peer within the PSTN.

For this to work, moodle has already prepared the use of a phone feature which is known as secondary registration. If you look at Phone / User-1 / General, you will see Edward Hyde's  registration with your little PBX on the IP411LEFT. However, when you switch to the Phone / User-2 / General tab, then you'll see a similar registration form but with  different settings. A phone can have up to 6 concurrent registrations and it can work with all of them concurrently!

User-2 on the IP232 is registered to an extension in the Mannheim area of our simulated PSTN. When you switch to the Phone/State tab, you will see all configured registrations. Clicking on  the Active radio button changes the active registration on the phone (that is, the registration where your outgoing calls are made on - incoming calls are possible on all registrations at any time).

Give it a try and

• call 0 0621 34282398 from Jane Doe's phone (actually, you could use any phone except John Doe's).
  
• Edward's phone rings (with its  second identity. Note the calling number (CGPN): it is 342823 (your subscriber number) followed by Jane's extension (12) so you end up with 34282312
• take the call and have a short talk to yourself
• hang up and call back (pressing the R button two times within a short time)
• Jane's phone rings
  

So far so good and not that surprising.

Hiding extensions - signal switchboard

You may recall that we - when we worked through the previous book - ticked  the Hide own Number check-mark in the IP111's Phone / User-1 / Preferences settings (well, we actually did it in John Doe's Phone configuration stored in the PBX but as you already know, this ends up the same). So John will do his calls with the CGPN suppressed.

So when you call 0 0621 34282398 from John Doe's phone, you will see a call  from anonymous arriving at Edward's alter ego.

Do you remember why Jane would see John's extension instead of anonymous when he calls her internally?
Hint: this is a global PBX setting

Now suppose that hiding extensions is your company policy. Clearly, you do not want to rely on your users to set their preferences right. To enforce this policy globally, let us return to the Trunk object's properties as there are several options to do that.

To enforce sending out the same extension for all users (e.g. the switchboard's extension -0):

•  set the Outgoing Calls CGPN to 0 (which is the trunk's Number and hence diverted to the Loopback destination when dialed-to in an incoming call) in the Trunk tab of the trunk object (PBX / Objects)
• on Jane Doe's IP112, call 0 0621 34282398 again
  
• Edward's IP232 will alert and  show a call from a subscriber 06213428230 (or 3428230, depending if your country supports area codes or not)
  

As you can see, Jane Doe's extension is now hidden and a 0 is shown instead at the end.

You can do the same call from John Doe:

• on the IP111, call 0 0621 34282398 again
• the call alerts on the IP232 and shows anonymous as CGPN again
  

Individual CLIR settings on a phone override the Outgoing Calls CGPN setting.

Hiding extensions - signal anonymous

We can also force all calls to go out as anonymous:

•  tick the Outgoing Calls restricted check-mark in the Trunk tab of the PBX's trunk object
  
• on Jane Doe's IP112, call 0 0621 34282398 again
  
• Edward's IP232 will alert and show a call from a subscriber anonymous like with calls from John before

This is because the CGPN is entirely restricted now for all outgoing calls via the trunk line, also for Jane Doe's calls.

Hiding extensions - signal extension or switchboard

Unfortunately, in real life, both version we've looked at so far have their drawbacks:

• setting all outbound calls to anonymous is perceived as unfriendly (to say the least) nowadays
• setting all outbound calls to the switchboard may be undesirable if users sometimes do want to signal their real extension (for example to call their beloved ones)

Wouldn't it be nice to signal the extension by default but signal the switchboard if the user chooses so?

Luckily enough, we can tweak the system so that a specific extension (the switchboard in our example) is sent, if the user turns on CLIR. In our setup, Jane would send -12 but John would send -0 then.

Outbound call routing

The Trunk PBX object does not have an option to do that. To learn how we can achieve that anyway, we need to understand how the outbound call routing is done.

You might remember the drawing showing the relation between SIP trunk, "Relay" and the PBX in the innovaphone overall Product Design. Thought it to be boring stuff? Now is the time you'll need it

 Outbound call routing

An outbound call would flow

• from the phone
  
• to the PBX
• to the VoIP interface that connects the relay to the PBX's Trunk object
• through the routing engine
• to the SIP interface
• to the provider

Now we'll look into the routing engine a bit deeper cause this is going to be our friend when it comes to implementing above requirement. In the other book it says:

In many cases, calls from interfaces to on-behalf registrations are straight back and forth without any manipulation. However, in certain scenarios, call routing can be more sophisticated.

Here we go!

The power is in the routing engine which is controlled by the routing table. The routing table can do 2 things:

• it can decide to which interface a call is sent based on CDPN (CalleD Party Number) and CGPN (CallinG Party Number)
• it can modify both CDPN and CGPN

The relay and hence the routing table is always on the box where the SIP interface is, not on the box where the PBX is. In our case, it doesn't make a difference though as both are located on the same box (your IP411LEFT).

In our case, modifying the CGPN is what we're aiming at. So let us  look at the routing table at Gateway / Routes . Each line is a rule in the form

source-interface CDPN-tomatch -> CDPN-replacement destination-interface counter CGPN-tomatch -> CGPN-replacement

that specifies

• From
  The source-interface the call came in to the routing engine. Names for interfaces are like
  
  
• SIPx (SIP trunks)
• BRIx (ISDN basic rate)
• PRIx (ISDN primary rate)
• TELx (analog devices such as phones or fax devices)
• FXOx (analog trunk lines)

Each type also has an R-type variation, which denotes the complementary VoIP interface that registers with the PBX (called Voip instance in the picture above): RSx (SIPx), RBx (BRIx), RPx (PRIx), RABx (TELx), RFx (FXOx)

• a CDPN map of the form tomatch -> replacement
  a rule is applied only if the CDPN head-matches tomatch. The matching part is then replaced by the replacement
  
  
• To
  The destination-interface the call shall be routed to
  
  
• flags
  
  
• Counter
  A counter that allows to limit the number of calls to or from interfaces
  
  
• a CGPN map of the form tomatch -> replacement
  like the CDPN map but is applied to the CGPN if it head-matches tomatch

As you know, moodle has pre-configured your trunk miraculously and thereby created a routing table too. However, in fact it has simply configured your trunk the way the Trunks PbxManager plugin would do when you add a new trunk (with one little exception).

You can read a lot about routes in  Gateway/Routes,  Gateway/Routes/Map and  Gateway/CGPN-Maps. Here it is enough to look at the  highlighted map and the map before.

In the first map

• From is RS1 (so it is the PBX connector for the SIP1 interface)
• the CDPN map is empty (we just have the ->). What you need to understand is that an empty tomatch matches the head of any CDPN! So all CDPNs match (the empty string) and the matching part (which is also an empty string) is replaced by nothing. So the map is applied to all calls and the CDPN is left unchanged
• To is TONE
  This is a special pseudo interface that does nothing but providing a dial tone. This is used for overlapped dialing when the user goes off-hook and dials 0. The user then would expect to hear a dial-tone. In the good old days of analog or ISDN lines, the PSTN would provide it. But nowadays SIP trunks can't. So the relay does

In the second map (the highlighted one) From stays the same (this is why these maps are grouped as they all apply to the same source interface):

• the CDPN map is empty again
• To is SIP1, our SIP trunk interface
  
• tomatch in the CGPN map is R!
  ! matches everything. So with this map, just any CGPN would match and consequently be replaced with the replacement
  R only matches calls with CLIR
  So map is applied to all calls with CLIR. When such a map having an R is applied, then the CLIR is cleared (of course, why would you want to apply replacement if the CGPN is restricted anyway?)
  
• replacement is 004962134282310 which is the loopback number (extension 0)

This second map is what is implementing our magic here! It sends out all CLIR calls with our switchboard extension instead.

But hey, what happens to calls without CLIR?

Look at the little v in the flags. It stands for Verify CGPN and says that the map must not be applied unless the CGPN matches. Calls without CLIR do not match our tomatch from above, so the map wouldn't be applied.

But wait, hey, if we have this wonderful rule, why is John Doe's call sent out as anonymous then?

Look at the picture again. The second map (the one that is highlighted) has a gray target interface. That means it is disabled (this was the "little exception").

To fix that

• click on the CDPN map (the ->)
  the  rule editor opens
  
• uncheck the Disable check-mark
• save the rule
• open the trunk PBX object
  
• uncheck the Outgoing Calls restricted check-mark
• clear the Outgoing calls CGPN field
  

If you now

• call from John Doe (who still has CLIR enabled) to 0 0621 34282398 again
  You'll see the -0 extension (switchboard) signaled
  
• call the same number from Jane Doe (who has no CLIR set)
  You'll see the -12 extension (Jane) signaled

Eh voilà!

The routing engine is only half of the story. After the call passed the routing engine, the call is forwarded to the target interface. In our example, the destination interface is the SIP1 interface. At this point, so-called  interface maps are applied, which can be edited by pressing  the + icon next to the interface. The purpose of interface maps is to adjust CDPN or CGPN numbers, either in the inbound or in the outbound direction. This is the reason why you see 4 different sections in the interface map screen. Depending on the direction and party of that call, different maps are used to adjust the number.

To come back to our previous outbound call example, we will take a closer look at  the CGPN Out maps of our SIP1 interface. All of those three maps have the same purpose. They normalize the number to the international format and put an international flag in front. The normalization depends on the received prefix.

You may wonder why the international flag is prepended. You might think since the call goes to a SIP provider instead of ISDN, the international flag is useless. This is not true, because the SIP interface has a function to interwork an international flag to a + symbol.

In other words, the number 004962134282310 which we sent to the SIP interface is mapped to +4962134282310 by the interface map and the SIP stack.

Syslog

When working with the routing engine in Gateway/Routes it is often very good to debug what's happening when executing our Routes and maps. This can be done with the Maintenance/Logging tab on the box that has the interface.

To  see how that works, we

• navigate to Maintenance / Diagnostics / Logging
• tick the Gateway Calls check-mark (and clear all others)
• save the settings
  
• click on the syslog link
• call from John Doe (who still has CLIR enabled) to 0 0621 34282398 again

Here is what you see:

There is something coming in to the routing engine, so a new call ("CALL 0") is allocated
20200317-204028 CALL 0 Alloc

The call comes from the RS1 interface, which is the registration to our Trunk object (and we don't know yet where it goes to)
20200317-204028 CALL 0 A:Call -> / RS1::->*::

It is from extension 14 but the CGPN is hidden (hence the ``R´´ in front of the 14), calling 34282398 and goes to the TONE interface
20200317-204028 CALL 0 B:Call R14:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->TONE:34282398:

The TONE interface can not complete the call (remember: it is just for providing the dial tone), so it rejects the call
20200317-204028 CALL 0 B:Rel R14:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->TONE:34282398: Cause: Resources unavailable, unspecified

So it is sent to SIP1 (our simulated SIP provider)
20200317-204028 CALL 0 B:Call 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:

The called party alerts
20200317-204028 CALL 0 B:Alert 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:

Both sides release the call (actually, the A side which is the caller John Doe, hangs up first)
20200317-204030 CALL 0 A:Rel 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:
20200317-204030 CALL 0 B:Rel 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398: Cause: Normal call clearing
20200317-204030 CALL 0 Free

Syslog (contd.)

Well, fair enough. We have seen what happened. But to debug a routing table we also need to understand why all this happen.

 Easy enough, we simply

• go back to Maintenance/Logging
• tick the Gateway Routing check-mark in addition to the Gateway Calls check-mark
• save the settings
  
• click on the syslog link
• call from John Doe (who still has CLIR enabled) to 0 0621 34282398 again

Whew, this is  quite a bit more stuff!

You already know some of the lines (those marked as CALL), so let's see what's new (which are those marked ROUTE):

20200317-211829 CALL 1 Alloc
20200317-211829 CALL 1 A:Call -> / RS1::->*::

The call goes to RS1's interface map

20200317-211829 ROUTE 1 INTERFACE MAP if=RS1 CGPN-In R14->R14, CDPN-In 34282398->34282398, DGPN-In ->

In our case, this interface map actually does nothing as neither CGPN (R14) nor CDPN (34282398) are modified

The routing engine then looks to evaluate the second route (RT2). The first route is irrelevant as it is for calls from SIP1 (the SIP provider) to RS1 (the Trunk)
20200317-211829 ROUTE 1 EVAL ROUTE route=RT2

In this route, the first map is evaluated
20200317-211829 ROUTE 1 EVAL MAP route=RT2 map=1 dest='TONE' in=''->out=''

The CDP is ok (which is not surprising cause the tomatch field is empty and therefore matches all CDPNs)

20200317-211829 ROUTE 1 MAP(CDPN-MATCH OK) route=RT2 map=1 dest='TONE' in=''->out=''

So the map is applied to the CDPN (which actually does nothing as the map replaces nothing by nothing)

20200317-211829 ROUTE 1 APPLY CDPN-MAP in='34282398'->out='34282398'

The routing engine is happy to send the call to the TONE interface

20200317-211829 ROUTE 1 SUCCESS route=RT2 map=1 dest='TONE' in=''->out=''

the TONE interface also has an interface map which does nothing

20200317-211829 ROUTE 1 INTERFACE MAP if=TONE CGPN-Out R14->R14, CDPN-Out 34282398->34282398, DGPN-Out ->

20200317-211829 CALL 1 B:Call R14:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->TONE:34282398:

20200317-211829 CALL 1 B:Rel R14:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->TONE:34282398: Cause: Resources unavailable, unspecified

once the TONE interface rejected the call, RT2 is evaluated again

20200317-211829 ROUTE 1 EVAL ROUTE route=RT2

20200317-211829 ROUTE 1 EVAL MAP route=RT2 map=1 dest='TONE' in=''->out=''
20200317-211829 ROUTE 1 MAP(CDPN-MATCH OK) route=RT2 map=1 dest='TONE' in=''->out=''

but since this map already has been executed before, the routing engine skips to the next map

20200317-211829 ROUTE 1 CONTINUE TO NEXT MAP route=RT2 map=1 dest='TONE' in=''->out='' reason='retry>0' found=false

which is map2

20200317-211829 ROUTE 1 EVAL MAP route=RT2 map=2 dest='SIP1' in=''->out=''

again, the CDPN matches (empty tomatch field)

20200317-211829 ROUTE 1 MAP(CDPN-MATCH OK) route=RT2 map=2 dest='SIP1' in=''->out=''

so the CGPN match is evaluated. Note that this time, the CGPN map is not empty (R14->004962134282310). In the map, the Verify CGPN check-mark is ticked (hence the ``v´´ in the table), so the map is ony executed if the CGPN matches. The specified CGPN to be matched is R! which means

• it must be restricted (R)
• and any digit combination may follow (!)

the actual CGPN matches (as the call is from John Doe with extension 14 and he has CLIR set on his phone), so both the CGPN and CDPN maps are applied
20200317-211829 ROUTE 1 EVAL CGPN-MAP cgpn=R14 verify=true in=''->out='004962134282310'

20200317-211829 ROUTE 1 EVAL CGPN-MAP SUCCESS in=''->out='004962134282310'
20200317-211829 ROUTE 1 APPLY CGPN-MAP in='R14'->out='004962134282310'
20200317-211829 ROUTE 1 APPLY CDPN-MAP in='34282398'->out='34282398'

The next maps are for other extensions, so their CGPN map does not match

20200317-211829 ROUTE 1 CONTINUE TO NEXT MAP route=RT2 map=3 dest='SIP1' in=''->out='' reason='verify cgpn failed' found=false

20200317-211829 ROUTE 1 CONTINUE TO NEXT MAP route=RT2 map=4 dest='SIP1' in=''->out='' reason='verify cgpn failed' found=false
20200317-211829 ROUTE 1 CONTINUE TO NEXT MAP route=RT2 map=5 dest='SIP1' in=''->out='' reason='verify cgpn failed' found=false

since there was a map that matched, the second map of this route is executed and the call is sent to SIP1 (our SIP Provider)

20200317-211829 ROUTE 1 SUCCESS route=RT2 map=2 dest='SIP1' in=''->out=''

The outgoing interface maps of SIP1 are applied (which only changes the CGPN sent into the international format

20200317-211829 ROUTE 1 INTERFACE MAP if=SIP1 CGPN-Out 004962134282310->I4962134282310, CDPN-Out 34282398->34282398, DGPN-Out ->I496213428231

and the call processing takes place as you already have seen

20200317-211829 CALL 1 B:Call 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:

20200317-211829 CALL 1 B:Alert 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:
20200317-211831 CALL 1 A:Rel 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398:
20200317-211831 CALL 1 B:Rel 004962134282310:john.doe@dvl-ckl2.net->34282398 / RS1:R14:->SIP1:34282398: Cause: Normal call clearing
20200317-211832 CALL 1 Free

Looks a bit weird I know. But trust me, as soon as you have played around a bit with it, it turns out to be a valuable tool when it comes to debugging a routing table.

Btw: the interface maps (which are applied when a call is received from or sent to an interface) are  defined along with the interface definition (so it's in Gateway/SIP for the SIP1 interface).

You can find a comprehensive description of all the features in

•  Gateway/Routes
•  Gateway/Routes/Map
•  Gateway/CGPN-Maps
  

Connecting diverted Calls early

When incoming calls are diverted externally and the destination is slow (e.g. a cellular / GSM phone), the caller (or the network equipment involved) might get impatient before the destination finally alerts. Also, when the call to the destination fails and there is a diagnostic in-band message, the original caller will not be able to hear it (as the call is not yet connected).

 Setting the Fake Connect on inc. Call property will connect the original call as soon as in-band info (such as a message or a call-progress tone) is available from the destination even if the destination did not connect the call already.

The Boolean Object

As already discussed in the More on advanced PBX object properties and behavior book, a  Boolean object can be configured to define generic conditions.

The status can be set by the PBX automatically depending on time, day of week and date (depending on the  Day of week settings). It then has either state false(automatic) or true(automatic).

You can  check the current state of your Boolean objects on your PBX at the bottom of the PBX / Config / Filter page.

Manual override

However, the automatic state can also be overridden manually so that it has either state false(manual) or true(manual). Of course the administrator can do this either by using the  advanced UI or the  Time switches PbxManager plugin. This option is also available  in the Boolean end-user App in myApps (we already looked at it before).

The check-mark on the right (next to the Edit button)  indicates the boolean's state (the video was taken on a Saturday afternoon ).

Managing from abroad

Sometimes, users need to check or modify the boolean state when they do not have access to myApps. This can be done using its DTMF interface. To use this, you would simply call into the Boolean object (which then probably needs a Number (a.k.a. extension) so you can call it with a normal phone, which otherwise is not required). The PBX would then report the current status with a voice prompt.

Also, to modify its state, the following DTMF codes are available:

• 0 - Clear Manual Override, i.e. switch to automatic mode
  
• 11 - Manual Override On, i.e. switch to manual override TRUE
• 10 - Manual Override Off, i.e. switch to manual override FALSE

If using the call-interface is desired, you should provide appropriate Announcements (as they are not hard-coded in the PBX). They can be configured in  the object's Boolean tab.

Providing the announcements

First of all, you need to have the announcement files. You can create them yourself of course. But for the purpose of this course, the ones we have prepared for you should do.

You can access the prepared announcement files by simply pasting the URL http://46.232.228.41/DRIVE/CF0/training/announcements/ in to your Windows File Explorer. This should give you a list of quite a number of files. We are interested in the  files starting with boolean-.

If you have issues with accessing the files with Windows File Explorer you can also use WinSCP if you have installed it or even paste the URL in the address bar of your web browser. If you do so, you will need to first download all the boolean-* files into a local folder.

As a second option, all files can be found  here as well.

As you probably already have guessed, we will use the Files App to store the announcements.

To store the files in your Files App

• start the Files App
• create a new folder called boolean
•  share this folder in the Share as link with filekey mode
• navigate to the new folder
• drag all the files from the source to the Files App
•  obtain the fileskey from the Folder info and copy it to the clipboard

The Files App won't let everybody access the files. The proper fileskey is required.

In fact, you could also share the files using the Share with user and password mode. This is perfectly OK but it requires a slightly more difficult configuration as you then would need to configure the Authenticated URLs in the PBX's Services / HTTP / Client settings.

Configuring the Boolean object to use the announcements

As mentioned before, the announcement URLs are configured in  the object's Boolean tab.

You could think: great just let's copy the URL from the Files App's folder info (e.g.http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/boolean/<file>?fileskey=xt5U8WYEk7d1GHdm) and replace <file> with the filename (e.g. boolean-true.g711a). However, its not that straight forward:

• instead of using the original file suffix (as .g711a in boolean-true.g711a) we need to use .$coder instead (so we end up with boolean-true.$coder). This is because you cannot know upfront which coders are available on the device that calls in. The PBX would determine that dynamically for each call and replace $coder with the actual coder negotiated
• also, the PBX needs to know which type of announcement files you have made available so it knows which can be offered to calling devices during the negotiation. Therefore, we need to give the list of available coders as query argument (as e.g. in ?coder=g711a,g711u,g729,g722)
• it is probably a good idea to repeat the announcement once it has been fully played (if the caller has not understood it). This can be forced by adding the &repeat=true query argument
• finally, we have to add the proper fileskey as query argument (e.g. &fileskey=xt5U8WYEk7d1GHdm) which you obtained from the  Folder info before
  

Announcement URLs are used in many places in the system (you already have used them in waiting queues). See Announcements  PBX/Objects/Waiting Queue for more tricks like &repeat=true!

So you end up with something like

• http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/boolean/boolean-true.$coder?coder=g711a,g711u,g729,g722&repeat=true&fileskey=yourfileskey for Announcements (URL) / TRUE
• http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/boolean/boolean-false.$coder?coder=g711a,g711u,g729,g722&repeat=true&fileskey=yourfileskey for Announcements (URL) / FALSE
• http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/boolean/boolean-manual-true.$coder?coder=g711a,g711u,g729,g722&repeat=true&fileskey=yourfileskey for Announcements (URL) if manual override is active (optional) / TRUE
• http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/boolean/boolean-manual-false.$coder?coder=g711a,g711u,g729,g722&repeat=true&fileskey=yourfileskey for Announcements (URL) if manual override is active (optional) / FALSE

Fortunately, we have already prepared your boolean object if-Working hours accordingly.

However, you still need to  paste your own fileskey in to all the URLs.

Give it a try and call your boolean object now (call #5): you should hear an announcement now that lets you know the state.

Changing the state with DTMF

As mentioned before, the object also lets you change the boolean's state within the call.

To try it out

• open  the IF-WORKING HOURS App in myApps
• if either manual on or off is ticked, turn it off
• call #5 (the boolean object if-Working hours)
• in the call to the boolean, type 11 (Manual Override On)
  see how  manual on is checked in the App and the check-mark on the right appears
• call the boolean again
• type 10 (Manual Override Off)
  see how manual off is checked and the check-mark on the right disappears
• call the boolean again
• type 0 (Clear Manual Override)
  see how both manual off and on is cleared. Whether the check-mark on the right appears or not depends on the current weekday and time
  

Using the Boolean-Object Function Key

The  Boolean Object function key can be defined and used to monitor and set a  boolean object conveniently. Like with Pickup and Partner keys, Boolean monitoring works with subscriptions, so you need to tick  the Subscribe for Dialog Info for it to work.

As always with subscriptions, the user monitoring the boolean function key must have access rights for the information required. In this case, the information the function key needs is the Calls information (Calls with Number would be OK but is not required).

When the  Toggle State check-mark is ticked, then pressing the function key will toggle through the possible states. Otherwise the function key will work like a Dial function key and initiate a call to the target boolean object and the user can set the state using the object's  DTMF codes as described in the previous chapter.

---

Richard Roe shall be able to monitor and change our sample boolean object (if-Working hours) with a function key. So we need to

• make sure Richard has access to if-Working hours's Calls information.
  We have two options to achieve this:
  
  
• we can put both Richard Roe and if-Working hours in to the  same group and have Richard be an active member of it (note the asterisk (*) behind the group name for Richard indicating active membership, see  PBX/Objects for more details)
• we can modify if-Working hours's Visibility settings so that Richard has  access to the Calls information. See  PBX/Objects/Visibility for more details
  
  
• configure the function key
  

To ensure access, we will use the group approach:

• add a  (new) group monitor-if-working to the boolean object if-Working hours
  
  Note that you cannot use the Groups PBX Manager plugin to do this, unfortunately. The plugin allows to assign groups to User type objects only
  
  
• add the same group to Richard Roe with active membership

in the PBX's list of objects

PBX / Objects

click on the PBX name (hq) on the left and then on the name of the group (monitor-if-working) - see how only objects in this group  are shown

to create the function key:

• open the function key definitions for User-1 on Richard Roe's IP222 Phone / User-1 / Function-Keys (as you already know, all these settings will be replicated back to Richard's PBX User object)
• add a Boolean Object function key on position (Key) #2
• set the Text property for Automatic Off State to Off
• set the Text property for the following states to On, Override off and Override on
• set the Number property to #5 (the Number of the boolean object to monitor)
• tick the Subscribe for Dialog Info check-mark (see above)
• to allow Richard to modify the boolean's state, tick the Toggle State check-mark
• save  the definition,
  
  see the function  appear on Richard's home screen
  
  
•  toggle through the states and use one of the methods described in the previous chapter to monitor the changes
  

Amazing that you guys have made it this far! As a well-deserved thank-you, we'll show you another little trick:

• toggle to one of the manual modes (Override on or Override off) using Richard's function key
• from John Doe's IP111, call #50

At this point, the display on the IP232 will show On again (well, most likely, except you are doing this course out of business hours in which case it will show Off).

You have learned en-passant, that it is not really necessary to type DTMF digits to the boolean object when calling it. You can as well send them right away as part of the called party number (in this case, #5 is the Number of the boolean object and 0 is the command code to switch back to automatic mode, sent appended to the called party number).

For some users who do not want to fiddle around with boolean function keys, DTMF codes or the boolean App in myApps, you could think of providing  Phone/User/Function-Keys/Dial function keys which simply call the DTMF object's number plus the desired code.

In fact, you do not need to specify all boolean states in the function key. If you leave the Text property empty for a state, the state will be skipped by the function key. You should then make sure that the boolean never is in the state you have omitted (for example initially).

The Call Broadcast Object

The  PBX/Objects/Call Broadcast object can be configured to define an extension that when called distributes the call to many other objects which are members of the same group the call broadcast object itself is an active member of. In other words, it sends the call to all members of a group and must be active member of this group itself.

In a way, this is much like having an ordinary User object with multiple endpoints registered. However, with the Call Broadcast object, all called users can have different numbers.

Furthermore, diversions set on the called users are normally not executed! You can change this by setting the  Execute Group Member Diversions property.

Round Robin Mode

Setting the  Round Robin Timeout s property will turn on a different call distribution method. Calls will not be sent to all group users. Instead, the call will be sent to one of the group members first. Whenever the specified time-out elapses, one more member is called.

If a user takes a call, the Call Broadcast object will call another user first for the next call.

---

Let us define an extension that - when called - rings all phones in group-Team-1 in a round robin fashion.

• create a group group-Team-1 by assigning active membership to Henry Jekyll
  
  This group already exists if you did the optional group pickup configuration in the previous book More on advanced PBX object properties and behavior: Group Pickup
  
  
• assign the same group membership to Edward Hyde
  
  
• create a  new Call Broadcast object called Team1 and define Number #4 for it
  
  
• set the  Round Robin Timeout property to 3
  
  
• assign the new object to group-Team-1  as an active member
  
  
• from Jane Doe's IP112, call #4
  At this point, either Edward Hyde's IP232 or Henry Jeckyll's analog phone will ring. Wait 3 seconds and the other phone will ring too
  
  
• take the call on the phone that rang first and hang up then
  
  
• call again
  note that now the other phone rings first!

Call forward on

It is possible to set CFU, CFNR and CFB:

• CFU is obvious, it effectively disables the call broadcast and diverts the call somewhere else
• CFNR is obvious too, it will forward the call when it has not been taken by anyone in the group within the time
  To try it, you can  set a CFNR to 13 (Richard Roe) on the broadcast and  set the Response Timeout property to 5.
  When you call it again, the first phone will ring followed by the second phone after 3 seconds (Round Robin Timeout[s] is set to 3) and after another 2 seconds the call is forwarded to Richard
• CFB is executed when all of the group members are busy (and have call waiting disabled!)
  To try it, you can set a CFB to 13 (Richard Roe) on the broadcast.  Turn off call waiting in the Account settings of the IP232
• go off-hook on the IP232 (Edward) and the analog phone (Henry)
• from John Doe, call the broadcast again
  The call is sent to Richard immediately, as both Edward and Henry are busy (and do not accept call-waiting)

Registering with

Users can register with the Call Broadcast object. However, this is not a recommended scenario. In rare case, this is done to set call forward for a Call Broadcast object from a telephone.

The Waiting Queue Object

You have already worked quite a bit with the  Waiting Queue object, which is one of the most powerful PBX objects, in the IT Connect training. In this chapter, we'll look at a few aspects which have not been discussed there.

Call forwards for agents

For the waiting queue to work correctly, it must be able to monitor the busy state of their agents (which is done by monitoring all users who belong to certain groups). For this reason, call forwards set for the agent are ignored.

The only call forwarding that is effective for an agent as far as calls from the waiting queue are concerned is a CFU. If an agent has a CFU and the queue has the CFU disables Operator check-mark ticked then the agent will be ignored by the waiting queue.

However, if the Excute Operator CFB/CFNR check-mark is ticked, then busy and no response forwards set by the agent are executed (see  PBX/Objects/Waiting Queue for details).

Calling busy operators

It might be useful to call operators even though they are busy. For example, if your agents also do normal phone calls (not serving the waiting queue callers), then calling them could cause the agent to terminate the current call (of course only if the agent has call-waiting enabled).

Registering with a Waiting Queue

An endpoint can register with a waiting queue object directly. Such endpoints are treated as operators and will be able to set call forwards for the Waiting Queue object itself conveniently (e.g. using functions keys). If you do not need this option however, we strongly recommend to disable any registrations on the waiting queue (as like for all other objects where you do not expect registrations on)!

Most often, such a registration is done on a temporary registration on a phone done with the  Phone/User/Function-Keys/Hot-Desking function key.

Valid agent PBX object types

Waiting Queue operators must be User objects. It is for example not possible to use a  Call Broadcast object as operator. Also, no call forwards set for operators are honored. Finally,  fork destinations set for operators are not evaluated (however Mobility is but this is something won't look into in this course).

Announcement URL tricks

When we were looking at the PBX Boolean object, we talked about some URL trick (using &repeat=true in this case). See the section regarding announcements in  PBX/Objects/Waiting Queue for more details.

One of the tweaks is especially interesting for waiting queues: the #p placeholder. It only works with waiting queues and is replaced by the caller's current position in the queue (with 0 being on the top of the queue). Using e.g.

http://apps.dvl-ckl2.net/dvl-ckl2.net/files/UI/wq/position#p.$coder?coder=g711a,g711u,g729,g722&fileskey=yourfileskey

as second announcement will retrieve files position2.g711, position1.g711 and position0.g711 before the caller is connected to an agent.

Hiding the operators extension

If you run a waiting queue, you usually do not want callers to know the agent's extension (as the caller then probably would try to call the agent directly, circumventing the waiting queue policies).

This can be achieved by ticking the Hide operator check-mark in the Waiting Queues PbxManager plugin (or the Hide Connected Endpoint check.mark in the advanced UI, both are the same flags, just different names). In fact, you almost always want this behavior and this is why the PbxManager plugin turns it on by default. But you can turn it off if need be.

Waiting Queue and the Number Property

In fact, the waiting queue does not need a number to work. The only thing is that users may want to quickly set a call forward to the waiting queue, for example if they leave the office. This is easier if it can be done with a number.

Providing a wrap-up time

Very often, the agent is expected to need a wrap-up time after the call is finished. During this time, no next call should be offered to the agent.

This can easily be implemented by ticking both the Presence Disables Operator and Set Operator Presence check-mark and specifying a Clear after ... s value. When the agent takes a call, the presence is set to Busy. As soon as the agent finishes the call and the timeout is elapsed, the presence is set to Available again. Due to the Presence Disables Operator setting, the agent does not receive any further calls in this time frame.

More Variations

The Waiting Queue object has a number of options to modify the strategy. Please find a description of all the options in  PBX/Objects/Waiting Queue.

Using the Join Group Function Key

When operators shall be assigned dynamically, we have already seen in the IT Connect training that group memberships can be changed in the personal Profile App.

However, the  Join Group function key can also be used.

You would set the Group Identification property to the name of the primary or secondary group used by the waiting queue.

For the Join Group function key to work, the user must have the group assigned as either dynamic-in or dynamic-out (as opposed to static)!

---

Let us assume we want give Edward Hyde the option of temporarily get rid of the group-Team-1 membership sometimes, so he doesn't receive the calls for Team1 even if he is in the office (and thus has no CFU set).

We fix this by letting him join/leave the group-Team-1 group with a function key:

• on Edward Hyde's Phone / User-1 / Function-Keys,  add a Join Group function key for Edward Hyde on position (Key) #7
  
•  set Text for the Idle State to Team1 off
  
• set Text for the Active State to Team1 on
  
• set the Group Identification property to group-Team-1 (the name of the group used to define the Team1 call broadcast)
  
• change Edward Hyde's group membership for this group  from Static to Dynamic-In
  
  At this point, you will see the new function key  labeled Team1 on
  
  
• press the new function key and notice how the state changes
  
• set the state to Team1 off
  
• call #4 (the Team1 broadcast) from John Doe again
  
  At this point, Edward will not receive any calls from the Team1 group
  
  
• go off-hook on the analog phone
• call #4 again
  
  At this point, the call will be forwarded to Richard Roe immediately even though Edward is not busy (as he is not in the group anymore, Henry is the only group member but busy, so the CFB set on Team1 fires)
  

Although we have exercised this with a Call Brodcast object, it will function with a Waiting Queue object just the same.

Call Forwards

A CFU set on a Waiting Queue object is executed immediately and effectively disables the waiting queue.

A CFNR is executed when the CFNR Response Timeout expires and no operator has accepted the call (even if the call is connected to an announcement), or if the first announcement ends and no second announcement is configured. So basically, the CFNR is executed if no operator takes the call within the timeout.

A CFB is executed if the Busy on ... calls condition or the Max Call/Operator(%) condition applies.

Call Forward when there are no Operators

An interesting case is when there is no operator at all (e.g. because all operators are in dynamic groups and logged off from the group). In this case, the Waiting Queue would still behave normally, that is, alert until the alert timeout expires and then play announcements (if any).

In many cases though, you want to handle this case specially. You can tick the CFNR on no Operators check-mark then. In this case, the Waiting Queue will respond with a no user responding  cause code. Also, if a CFNR is configured, it will be executed right away.