Advanced multiple endpoint calling with enterprise originate

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

For instance, you want to call Bill and Susan at the same time, but Bill prefers you to try his cell first, then try all of his landlines at the same time. Susan prefers you to call her desk first, then her cell, and then her home. This is a complicated problem and the solution to that problem 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 the regular originate. Originate is the term used to indicate making an outbound call. Although there is an originate command that can be used at the 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 not the bridge application and the originate command completely different? No! This is a common misconception, and it is incorrect. 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 at the 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 create 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/[e-mail]:_:{myoption=true}sofia/sip/[e-mail]"/> 
  </condition>
</extension>

<extension name="enterprise_originate2">
  <condition field="destination_number" expression="^(2001)$">
    <action application="bridge" data="{ignore_early_media=true}sofia/internal/[e-mail],sofia/sip/[e-mail]:_:sofia/internal/[e-mail],sofia/internal/[e-mail]"/> 
  </condition>
</extension>

How it works...

The entire input string is broken up 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

As you know, you can use the {var=val} syntax to define special variables to be set on all 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/[e-mail],[who=userB]sofia/sip/[e-mail]:_:{myvar=inner2}[who=userC]sofia/internal/[e-mail],[who=userD]sofia/internal/[e-mail]"/> 

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:

Channel	${ignore_early_media}	${myvar}	${who}
[e-mail]	true	inner1	userA
[e-mail]	true	inner1	userB
[e-mail]	true	inner2	userC
[e-mail]	true	inner2	userD

Once you know which syntax to use, it becomes a simple matter to set channel variables for individual 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 the enterprise originate, you must define the ringback variable if you want to send a ring tone back to the caller.

See also

To learn more about originate and enterprise originate, look at some of the 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.