Advanced multiple endpoint calling with enterprise originate

You've seen many ways of ringing multiple destinations with many options, but in some cases even this is not good enough. Say you want to call two destinations at once, but each of those two destinations is a separate set of simultaneous or sequential destinations.

For instance, you want to call Bill and Susan at the same time, but Bill prefers that you try his cell first, and then try all of his landlines at the same time. Susan, however, prefers that you call her desk first, then her cell, and finally her home. This is a complicated problem, and the solution to it is called enterprise originate. The term "enterprise" is used to indicate an increased level of indirection, dimension, or scale. Basically, you are doing everything the originate syntax has to offer, but you are doing entire originates in parallel in a sort of "super originate".

Getting ready

The first thing you need to do to take advantage of enterprise originate is to fully understand regular originate. Originate is the term used to indicate making an outbound call. Although there is an originate command that can be used at fs_cli, the method by which you mostly use the originate command is with the bridge dialplan application.

Tip

The bridge application versus the originate command

Why do we talk about a regular originate when discussing the bridge application? Are the bridge application and the originate command not completely different? No! This is a common misconception. The bridge application is used in the dialplan, but it does exactly the same thing that the originate command does—it creates a new call leg. In fact, bridge and originate use exactly the same code in the FreeSWITCH core. The only difference between the two is where they are used. The originate command is used in fs_cli to create a new call leg. The bridge application is used in the dialplan to create a new call to which an existing call leg can be connected or bridged.

You will need to open conf/dialplan/default.xml in a text editor or edit a new XML file in the conf/dialplan/default/ subdirectory.

How to do it...

The usage of enterprise originate is similar to the ring simultaneously example, but an alternate delimiter (:_:) is used:

<extension name="enterprise_originate">
<condition field="destination_number" expression="^(2000)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com:_:{myoption=true}sofia/internal/userB@local.pbx.com"/>
</condition>
</extension>

<extension name="enterprise_originate2">
<condition field="destination_number" expression="^(2001)$">
<action application="bridge" data="{ignore_early_media=true}sofia/internal/userA@local.pbx.com,sofia/internal/userB@local.pbx.com:_:sofia/internal/userC@local.pbx.com,sofia/internal/userD@local.pbx.com"/>
</condition>
</extension>

How it works...

The entire input string is broken down into smaller strings based on the :_: symbol.

Each of those smaller strings is fed to the regular originate engine in parallel, and the first channel to answer will be bridged to the caller. Once one endpoint answers, the rest of the calls in the enterprise will be canceled.

There's more...

Enterprise originate has a few special aspects to consider when using it to place calls.

Setting variables in enterprise originate

As you know, you can use the {var=val} syntax to define special variables to be set on all the channels produced by originate, and [var=val] to define variables per leg in a call with many simultaneous targets. Enterprise originate uses these as well, but remember that each string separated by the :_: delimiter is its own self-contained instance of originate, so {var=val} becomes local only to that single originate string. If you want to define variables to be set on every channel of every originate, you must define them at the very beginning of the string, using the <var=val> notation. This indicates that you should pass these variables to every leg inside every originate. Consider the following enterprise originate:

<action application="bridge" data="<ignore_early_media=true>{myvar=inner1}[who=userA]sofia/internal/userA@local.pbx.com,[who=userB]sofia/internal/userB@local.pbx.com:_:{myvar=inner2}[who=userC]sofia/internal/userC@local.pbx.com,[who=userD]sofia/internal/userD@local.pbx.com"/>

At first glance, this may seem confusing, but when you break it down, you can see what the values of the variables are for each channel. This table shows the values:

Once you know which syntax to use, it becomes a simple thing to set the channel variables for inpidual legs inside originates, or the entire enterprise originate.

Ringback

Unlike the regular originate, signaling cannot be passed back from one of the inner originates, because there are too many call paths open to properly handle it. Therefore, when using bridge with enterprise originate, you must define the ringback variable if you want to send a ringtone back to the caller.

See also

To learn more about originate and enterprise originate, look at some other examples in this chapter and study the default dialplan distributed with FreeSWITCH. There are several examples of the many things you can do when placing outbound calls found in conf/dialplan/default.xml.