Course12:Basic - PBX - Advanced Object Types

From innovaphone-wiki

Jump to: navigation, search

This book discusses the more advanced PBX object types.


Test Mode

It is recommended to use the fish-help.png test mode 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.

However, if you still have old style V10 test licenses on the box, it will not work. Save your licenses in to a file, then delete all licenses and turn on test mode.

The test mode is to be used both on the General / License and the General / License.

If you have not already done so, load the PBX_-_Advanced_Object_Types start configurations to devices now!

The Trunk Object

The fish-help.png Trunk Line object is typically used to register external interfaces (ISDN,SIP, VoIP-GWs) at the PBX. It therefore often represents the connection of a PBX to the PSTN. Here are some more details.

Handling incoming Calls

Incoming calls will normally be routed to the extension directly (DDI). However, if for some reason the extension is not reached, the fish-help.png Trunk object can be configured to handle this situation.

Dialling the Switchboard

Normally, calling the extension -0 from extern means calling the switchboard (assuming that 0 is you trunk line access code). For example, if you call +49 7031 73009 0, you will innovaphone's switchboard service.

From the PBX's point of view however, dialling -0 from extern means to dial in to the PBX and then dial out through the Trunk object again right away (again, assuming the Trunk object has Number 0).

To handle this situation, configure the Number (or Name) of the real switchboard into the Trunk object's Loopback property. Incoming calls that loop back to the trunk right away will be diverted to this number instead. Note that this may be just any PBX object, not only an ordinary fish-help.png User object. In many cases, this will be a fish-help.png Waiting Queue object (we will come back to this later).

Catching undeliverable Calls

Calls that can't be delivered can be handled by setting the Incomplete, Invalid, Busy, Rejected and No Answer property.

In many installations, all those properties will be set to the switchboards number.

Manipulating the CGPN

The fish-help.png 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 is rarely used with straight ISDN trunk lines (as ISDN does not use the Name property anyway), but can be useful when interworking to SIP or QSIG.

To play around with the Trunk's number handling, we need an external user. Fortunately, we have prepared some smile

Your IP811, which had not been used so far, actually runs something like a PSTN simulation. Also, the start config that has been loaded to the IP411LEFT include a basic trunk configuration which connects to this simulated PSTN. You can try that by simply calling the Sindelfingen fire brigade (call 0112 from any of your phones) .

Even more surprising is that we have some external PSTN subscribers already.
  • on the IP240, call 00511271
  • the IP222 will ring alert and show a call from a subscriber 07031/73009-12 (which is Jane Doe) to a user called Triton with subscriber number 271 (note that we called out to 00511 (which is the Hannover area code) 271 (Triton's subscriber number)
    Btw: if you see 0703144556612 as calling party number, you need to switch the cables in your IP811's BRI1 and BRI2 ports

For this to work, we used a phone feature which is known as secondary registration. If you look at Phone / User-1 / General, you will see Richard Roe's registration for your little PBX on the IP411LEFT.

However, if you look at Phone / User-2 / General,you will see registration data for a user called Triton on your IP811. This is how we simulate the external PTSN user.

How this PSTN simulation works is beyond the scope of this course. If you are curious of course, you may want to have a deeper look at it after the course.

Let us return to the Trunk object's properties.

  • In the Trunk object (PBX / Objects), screenshot.png set the Outgoing Calls CGPN to 0
  • on the IP240, call 00511271 again
  • the IP222 will ring alert and show a call from a subscriber 0703173009-0

As you can see, Jane Doe's extension is now hidden and a 0 is shown instead. You can do the same call to 00511271 from John Doe and again, will be signalled to Triton.

  • In the Trunk object (PBX / Objects), screenshot.png tick the Outgoing Calls restricted
  • on the IP240, call 00511271 again
  • the IP222 will ring alert and show a call from a subscriber anonymous

This is because for all outoing calls via the Trunk Line, also for the Jane Doe's calls, CGPN is entirely restricted now.

Connecting diverted Calls early

When incoming calls are diverted externally and the destination is slow (e.g. a cellular / GSM phone), the caller 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).

screenshot.png Setting the Fake Connect on inc. Call property will connect the original call as soon as inband info is available from the destination even if the destination did not connect the call already.

The Boolean Object

As already discussed in the PBX - Advanced Object Properties and Behaviour book, a fish-help.png Boolean object can be configured to define generic conditions.

The status of each boolean object can be set depending on time, day of week and date or can be set manually by calling the object and using DTMF codes.

DTMF codes:

  • 0 - Clear Manual Override, i.e. switch to the automatic mode rule according to current time of day
  • 11 - Manual Override On, i.e. apply the manual override TRUE rule
  • 10 - Manual Override Off, i.e. apply the manual override FALSE rule

If setting it with DTMF is desired, you should provide appropriate

Setting it manually (manual override), can also be done by using a fish-help.png Boolean-Object function.

In our PBX configuration, we have the if-Working hours boolean object. Let us configure it so that it can be queried and set by calling the object.
  • We have prepared some announcements for the 4 status case:

    •$coder?coder=g711a,g711u,g729,g722&repeat=true for automatic true
    •$coder?coder=g711a,g711u,g729,g722&repeat=true for automatic false
    •$coder?coder=g711a,g711u,g729,g722&repeat=true for manual true
    •$coder?coder=g711a,g711u,g729,g722&repeat=true for manual false

  • in the boolean object, screenshot.png set the Announcements fields
  • screenshot.png see the boolean status in PBX / Config / Filter
  • from any phone, call #5 (the Number of the boolean), do not hang up

At this point, you will hear an announcement telling you the current status.

  • In the call, type 10 (Manual Override Off)

You will hear a long tone and the call will be disconnected. If you look again at the PBX's boolean status page, you will screenshot.png see that it switched to false(manual).

  • call again and type 0

The boolean will be switched back to true(automatic).

While we are at announcements: as you have seen, announcements are prompt files which are retrieved by the PBX via HTTP (or HTTPS). There are some query args you can add to the announcement file URL which are actually interpreted by the PBX itself. For example, the &repeat=true in the URL tells the PBX to repeat the announcement endlessly. See Announcements fish-help.png PBX/Objects/Waiting Queue for more tricks!

Using the Boolean-Object Function Key

The fish-help.png Boolean Object function key can be defined and used to monitor and set a fish-help.png boolean object conveniently. Monitoring works through group indications.

When the Toggle State property is set, 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 fish-help.png DTMF codes.

Edward Hyde shall be able to monitor and change our sample boolean object.

  • screenshot.png configure a Boolean Object function key for Edward Hyde on position (Key) #5. Allow to toggle through the boolean states
  • create a new group and assign Edward Hyde as an active member
  • assign if-Working hours as passive member to this group
  • set screenshot.png Edward Hyde's Group Indication property to the new group
  • Toggle through the 3 states by touching the new function key on Edward's IP232
  • You can check the current setting by either call the boolean (#5) from any other phone and hear the announcement.

The function monitors the boolean status by virtue of the group indications we have configured. To verify this, do the following:

At this point, the display on the IP232 will show Business Hours again.

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, sent as appended called party number).

The Call Broadcast Object

The fish-help.png Call Broadcast object can be configured to define an extension that when called distributes the call to a many other objects that member 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 fish-help.png 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.

It is possible to set CFU, CFNR and CFB.

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.

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. When 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 a round robin fashion.

At this point, Edward Hyde, Richard Roe and John Doe's phone should be ringing sequentially (see above). Note that John Doe's CFU is not executed (even if you set if-Working hours to manual-false).

The Waiting Queue Object

The fish-help.png Waiting Queue is one of the most powerful PBX objects.

Incoming calls are put in the objects queue. They will stay in alerting mode until the time set in the Alert Timeout property has elapsed. The call will then connect and an announcement (as defined in the 1st Announcement and 2nd Announcement) is played. If the Alert Timeout property is left empty, no announcement is played and the call stays connected.

Any PBX user objects known to the waiting queue via the group mechanism are considered operators (a.k.a agents) for the queue. When an incoming call is queued, un-busy operators will be searched and the call will be sent to all of them.

When the Call busy Operators property is set, even busy operators are called.

When the CFU disables Operator property is set, operators that have a CFU will not be treated as operators (assuming they are not available and have thus set a CFU to e.g. their cellular phone).

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)!

Waiting Queue operators must be User objects. It is for example not possible to use a fish-help.png Call Broadcast object as operator. Also, no call forwards set for operators are honoured. Finally, fish-help.png fork destinations set for operators are not evaluated.

Let us define a waiting queue that handles incoming external calls to the switchboard. It shall alert a few seconds and then play some announcements until a waiting queue operator takes the call. Edward Hyde and Jane Doe should be operators.
At this point, Edward Hyde and Jane Doe's phone should be ringing and the caller hears an announcement.
  • do not take the call and listen to the announcement for a while

You will notice, that the there is a first announcement that is played once followed by a second announcement that is repeated. This is the default behaviour of the waiting queue (note that we did not specify the repeat=true query arg in the second announcements URL!).

You will also notice that as soon as the waiting queue connects the call (that is, as soon as the first announcement is played), the callers display shows the extension of the waiting queue. The display changes from 07031730090 to 0703173009xx (xx is the number of your waiting queue). This a result of the COLP service.

This may not be desired, as you may want to hide the extension of the switchboard service so that external callers can not call it directly.

  • to fix this, screenshot.png set the Hide Connected Endpoint property in the waiting queue
  • call again to 07031730090 and see the IP222's display - the switchboard's number is not shown
  • now call to an non-existing extension, say 88, 070317300988
  • you will be connected to the waiting queue again and the two phones will ring
This is because we have defined the waiting queue as target for all of the fish-help.png Trunk object's rerouting options.

Waiting Queue and the Number Property

You may ask yourself, why do I need to specifiy a Number for the waiting queue in the first place if I then have to hide it with Hide Connected Endpoint?

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.


As described before the Waiting Queue will usually connect incoming calls, play an announcement to the waiting caller and signal the waiting call to the subscribed operators.

The announcement to use by the Waiting Queue is specified by an URL and retrieved via HTTP from a Web server (e.g. CF card). By using additionally parameters in the URL, the way of playing the announcement can be changed. For example you can use this option to play a different announcement file depending on the position of the user in the queue. As always, have a look at the wiki for a current fish-help.png view of possible parameters.

Multi-Level and Round-Robin Mode


When a number of operators shall service the waiting queue and there is a number of extra operators which should only take calls when all regular operators are busy, the multi-level mode can be used.

To enable this, you need to have all operators in the group the waiting queue object is active in (as we already have seen before). In addition, you need an extra group where only the regular (or primary) operators and the waiting queue are members in. This group is set in the Primary Group property. When the primary operators do not take a call within the time set in the Primary Group Timeout property, all operators are alerted.

In addition, a load factor can be defined in the Max Call/Operator(%) property. This defines the number of concurrent calls a queue can take (including the calls currently handled by the primary operators) in relation to the number of primary operators. A value between 100% and 150% is a good starter. This calculation is made each time a call comes in.

Round Robin

As with the broadcast object, the waiting queue can be set into round-robin mode by setting the Round Robin Timeout property.

More Variations

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

Jane Doe has discovered that taking all incoming calls to the switchboard is boring. So she wants John Doe to take these calls and only if he does not take them within 5 seconds, the calls shall be presented to her and Edward Hyde as before.

At this point, John Doe's phone should ring screenshot.png showing a diverted call via Switchboard. After 5 seconds, both Jane's and Edward's phone will alert, showing the same call. This is the effect of the Primary Group and Primary Group Timeout settings.

Let us look at the handling of call forwards set on operators a bit.

  • set a CFU to 12 for John Doe (so that if Edward calls 11, the call alerts on Jane's IP240)
  • from the IP222, call 07031730090 again

At this point, John Doe's IP111 alerts. Note that the CFU set for John is not executed. This is because Waiting Queue objects calling operators never execute a call forward set for the operator.

Often, having a CFU set for a user means I am not in the office. In this case, it may make sense to treat this user as not available as far as the Waiting Queue is concerned. This behaviour is controlled by the CFU disables Operator check-mark.

At this point, John's phone stays idle and both Edward's and Jane's phones alert. This is because setting the CFU for John disables him as an operator for the Switchboard queue. So there is no operator left in the Primary Group and the regular operators are alerted without waiting for the Primary Group Timeout.

Using the Join Group Function Key

When operators shall be assigned dynamically, the fish-help.png Join Group function key can 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)!

John Doe needs to get rid of the Switchboard calls sometimes, even if he is in the office (and thus has no CFU set). We fix this by letting him join/leave the Switchboard's primary group with a function key.

At this point, John Doe's phone will ring.

  • leave the group
  • from the IP222, call 07031730090

This time, John's phone will not ring but Jane's und Edward's will do.

2-Stage Dialling

The Waiting Queue object can be used to implement 2-stage dialling in the PBX. 2-stage dialling allows people to call the Waiting Queue and control the call flow via DTMF tones while the announcement is played.

An example would be a central waiting queue announcing incoming callers that they called the company headquarters. Afterwards the caller can specify by pressing 1, 2 or some other digit the department to be connected to (i.e. welcome at innovaphone. Press 1 for the sales department ...).

Therefore the main function for 2-stage dialling is the mapping of DTMF tones to numbers. This screenshot.png can be done in the Maps tab of the Waiting Queue object (see the DTMF Destinations section in fish-help.png PBX/Objects/Waiting Queue).

Note that the numbers in the Dest. No column do not need to be complete. If further digits are required to complete the call, the user can dial those using DTMF tones.

An interesting form of a DTMF setting in the Maps is the dot (.). It matches any DTMF digit and the matched digit will be appended to the target number specified in the Dest. No column (possibly followed by further digits dialled by the user).

Alert: care should be taken to avoid users calling to unwanted destinations through DTMF maps. For example, if we want callers to be able to dial to any extension, we could be tempted to use a map like DTMF=. -> Dest. No empty. This allows callers to simply dial the extension when the announcement is heard to be connected to any extension. However, it also allows the caller to dial 0 followed by an external number. This way, anyone could call the waiting queue and dial-out to any external number on your cost!

You can not assign a Filter to the Waiting Queue object to disallow this. But you can screenshot.png catch the unwanted extension as part of the Maps.

Note that the order of DTMF maps is important (that is, maps are tried sequentially and executed on the first match).

We want to provide callers of the waiting queue a method to connect to any extension. This should be done by typing a star (*) followed by the extension.
  • screenshot.png add a DTMF map for *0 with Dest. Name Switchboard (catches attempts to dial out to the trunk)
  • add a DTMF map for * with no destination
  • press the Join Group function key on the IP111 until John Doe is not joined to the waiting queue's Primary Group any more
  • from the IP222, call 07031730090
  • do not take the call until you hear the announcement
  • on the IP222, type *11

At this point, you will be transferred to John Doe.

  • hang up and dial 07031730090 again from the IP222
  • wait for the announcement
  • on the IP222, type *0

Whenever you type *0, you will hear the alert tone and the first announcement again. This is because you will be transferred to the waiting queue again.

Advanced ACD Functions

The fish-help.png waiting queue supports a number of configuration options which are used in ACD style configurations, like the aforementioned Max Call/Operator property. In addition to this, there is a feature available using the Presence Disables Operator and Set Operator Presence properties.

Presence Disables Operator will inhibit calls from the waiting queue to an operator as long as there is a presence state known (more precisely, as long as an activity is set for the tel: device presence). This way, an operator can effectively remove himself from the set of available operators by setting an activity (e.g. using a fish-help.png presence function key or fish-help.png myPBX).

Moreover, an operator can be removed from the list of available operators automatically by setting his presence activity to Busy as soon as he accepts a call from the waiting queue. This is done if the Set Operator Presence check-mark is checked.

Finally, the presence activity can be cleared automatically after a timeout by setting the Clear after property to a number of seconds so the operator has to accept calls again.

Call Forwards

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

A CFNR is executed if the CFNR 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 case though, you want to handle this case specially. You can tick the no-op-no-response check-mark then. In this case, the Waiting Queue will respond with a no user responding cause code (fish-help.png ISDN Cause Codes). Also, if a CFNR is configured, it will be executed right away.

The EXTERN Object

The EXTERN object is not really an object. Instead, it is a property in the PBX's PBX / Config / General configuration tab called fish-help.png Route Root-Node External Calls to. This is sort of a catch-all function that allows calls to objects which are unknown to the PBX to be sent to a fall-back destination. A similar function has been discussed before with the Invalid property of the Trunk Line object. However, this is valid for calls coming in through the trunk only.

The catch-all target's Long Name must be set in the Route Root-Node External Calls property. Very often, a fish-help.png Gateway object is used to send such calls through the relay layer to a trunk line or a connected legacy PBX.

This is most often used in these scenarios
  • a VoIP PBX is looped-in to the trunk line of a legacy PBX
    In this scenario, you would want to route calls to everything you don't know yourself to the legacy PBX. The object configured would be a Gateway object where the tie line to the legacy PBX is registered
  • a PBX with no internal numbering plan
    smaller PBXs often have no internal numbering plan. In that situation, you would call out to external numbers without a trunk line access code (i.e. you do not precede the number with a 0). The local extension usually have "impossible" extension numbers (such as *1 to *9) to avoid conflicts with subscriber numbers in the local code. The object configured would be a Trunk object where the local trunk line is registered

The Route PBX-Node External Calls to property applies to multi-site installations only and is not covered thus in this course.
Personal tools