62.1. CTIVO resource

62.1. CTIVO resource
	Chapter 62. CTIVO - Virtual Office

The module Abilis Virtual Office (VO) is a new module of Abilis that allows the users to transfer to a distant location, fixed or mobile, your desk phone to work with all the features that make substantially indistinguishable from the actual location.

The cornerstone of this system is that there is a connection between the telephone distant location and the module VO using any of the available technologies (digital or analogue fixed line, cellular network, VoIP, etc) that may be supported by a data connection (GPRS, EDGE, 3G, HSPA, WiFi), making the remote equivalent to a local station and then being able to access services such as parking, second call, transfer with and without consultation, conferencing, call waiting, etc.

The connection to the remote location can be initiated either from the remote location or from the VO module using a sophisticated system of preferential pathways, for example, prefer the VoIP connection if available over the cellular network. It can also be ordered from the remote, but initiated by the VO module via the callback function, thus relieving the remote location to any cost.

Operation is via DTMF codes if there is only the telephone channel, but if a data connection is available the use of an appropriate application permits to send commands via a user-friendly graphical interface.

The application Abilisphone for Android and IPhone falls into the latter case, and is currently the only one available.

	Tip
	Interesting chapter: Chapter 86, Abilisphone - End user manual.

62.1.1. Key points

Typically the CTIVO of the Abilis has a channel to the user (outstation) and one or two channels to other stakeholders.

So the virtual user channel has different sides:

User side or Outstation side (it's the side connected to the virtual user)
Network side or Telephone network side (it's the side connected to virtual user's interlocutors)

The user can park the call, open another one and switch between the two before transfer via DTMF. The outstation has control of the call both in the case in which it was the originator or the recipient of the call.

Figure 62.1. Outstation connected via the virtual office to two stakeholders

The DTMF allows the control of the call, in example to perform a second and switching between the two calls. Whether it's a PSTN outstation whether it's a central of services for the virtual office management is the same matter. In case of Abilisphone the schema includes to data connection too.

Figure 62.2. Abilisphone connected via the virtual office to two stakeholders

Please note that via the data channel we will resolve the cases in which the DTMF are blocked by the operator of mobile telephony, then the Abilisphone feature to use of the data channel to control of the call (also GSM) isn't only an option but may be the only one applicable.

The data channel in addition to the call control allows various additional features that will be analyzed in detail in the section on data channel.

One difference to note between Abilisphone and the typical application is that for Abilisphone there is only one instance of the virtual office call while in the standard case there may be multiple instances (each with up to two calls on the same channel). So if Abilisphone is engaged in a GSM call a VoIP call will fail because the user is already "busy" with Abilis in other conversations via another channel audio.

62.1.2. Handling of phone numbers

In the Virtual Office telephone numbers are a crucial part for the correct identification and connectivity of the outstation.

Each VO USER:

May have assigned by the system administrator up to 10 numbers, mobile, landline or private.
May set which number where to be reachable from that moment on
May set up to three numbers to be called sequentially to reach him
May set up to two numbers to be called contemporary (fork) to reach him
May set the number to be used to present him in outgoing calls
May enable the call forwarding to be applied always, or on busy, on no answer on other causes
The configuration may occur:
- Via a web page
- If currently connected, via DTMF tones (there are limitations)
- Via data channel (Abilisphone)
The phone numbers may use any of equivalent formats, the Virtual Office will perform the conversions or the proper matching.
- u0376123
- n376123, if NAT-PREFIX:0
- u00390376123, if INT-PREFIX:00 and COUNTRY-CODE:39
- i390376123, if COUNTRY-CODE:39
The replacement of the phone numbers is managed automatically and autonomously by the Virtual Office. There are several conditions which require the replacement of the number, here are some example:
- The remote call from their mobile phone, e.g. 3331234, and the call should go out with the office number 029 876
- A call comes in to the office to the number 029876 and requires you to contact the remote location before the private VoIP number 101, and if not available at the phone number 3331234
Within the limits of what is allowed by the operator of the public network, always present calls with the "real calling number". This feature requires enabling the operator of the " redirecting number".

62.1.3. Calls from outstation to virtual office driver

Let's look at what happens to a call from the outstation that comes into CTIVO using a routing *toA.

Initially the user is identified by the caller number (note that a user may have multiple numbers associated).

Once the user was Identified the user may eventually directed to a postselection or a callback feature, if the user is enabled and the called number called matches, otherwise the virtual office proceeds to make a new call to the destination (via CTIR) and to stay in the middle.

In the case of postselection a continuous tone is directed to the user, in the case of a request for callback the call is turned down and the user is called to a configured number. In the case of management of active calls via the DTMF tones the CTIVO recognizes eventually them as commands to perform, for example, the second call, in the case of Abilisphone these controls may occur through data channel.

62.1.4. Calls from the virtual office driver to the outstation

If the virtual office is used to call a user then the alternative routings can be used to contact the user specified in the CTIVO parameters.

Once the user has been connected to the user can perform all the usual authorized operations (for example, open a new call and transfer the current one).

62.1.5. Basic DTMF protocol

Having just one active connection/call to the remote location of the user:

* + a pause of 1 sec: it holds the current call and send the dial tone audio to invite to perform the second one. Pressing it again, it unholds the call and aborts the second calls.
*xxxx: the first digit "x" has to be received within 1 sec from the received *, it holds the current call and starts the second call.

Having two active connections/calls:

* + a pause of 1 sec: it holds the current call. Replaying the command it unholds the calls.
*1: close the current calls and goes back to the held one.
*2: switch between calls.
*3: reject a call waiting.
*4: perform the transfer connecting the two calls.
*5: request a conference.
**: if the second * is sent within 1 sec from the first one than a DTMF * is sent in the audio channel.

The # is used only to force the closure of the called number, normally it isn't needed.

62.1.6. Activating the CTIVO resource

Add the resource to the Abilis system with the following command.

[09:08:14] ABILIS_CPX:a res:ctivo

COMMAND EXECUTED

The CTIVO resource may already exist in the system, but may not yet be active.

[09:10:00] ABILIS_CPX:s act res:ctivo

COMMAND EXECUTED

[15:20:51] ABILIS_CPX:save conf

COMMAND EXECUTED

[15:20:51] ABILIS_CPX:warm start

	Caution
	After adding the CTIVO active Abilis to make the resource running. Use the command save conf and restart Abilis (i.e. With warm start command)

62.1.7. CTIVO resource parameters

Use the command d p vs to show the parameters of the resource and use the command d p ctivo ? to display the meaning of the parameters.

[14:08:29] ABILIS_CPX:d p ctivo

RES:CtiVo ---------------------------------------------------------------------
Run    DESCR:CTI_Virtual_Office
       LOG:NO                        ACT:YES                 sesnum:20
       volog:DFT                     vologsize:200           CTIP-TYPE:USER
       PS-NUM:#                      CB-DELAY:5   CB-NRTY:1
       CB-NUM:#                      CB-CGO-NUM:#
       OUTDIAL-DIGIT:SYS (0)         CB-AUTO-CDO:#
       DJ:0      MJ:0                CB-AUTO-CDO-TOUT:2
       wdir:C:\APP\VO\
       - AP Data Channel Settings ---------------------------------------------
       ap-channels:10                ap-udp-locport:48484    AP-TOS:0-D
       AP-IPSRC:*                    AP-IPSRCLIST:#
       AP-AUTH-TOUT:20               AP-CONN-TOUT:20         AP-PS-TOUT:20
       AP-DTMF-LEN:200               AP-DTMF-SILENCE:100
       AP-NOTIFY-HOST:apnotify.abilis.net
       - AP provisioning ------------------------------------------------------
       AP-WIFI-DJ:100                AP-MOBILE-DJ:100
       AP-WIFI-MJ:350                AP-MOBILE-MJ:350
       AP-CHAT-TLS:NO                AP-CHAT-CHECK:10        
       AP-VOIP-CODERS:G.711,Spirit,G.729A
       - AP Link Evaluator thresholds to disable VoIP -------------------------
       AP-MAX-JITTER:200             AP-AVG-JITTER:100       AP-MAX-PCK-LOSS:5
       AP-MAX-JITTER-COUNT:1         AP-AVG-RTT:500

Meaning of the most important parameters:

LOG: Logging functionalities activation/deactivation.
ACT: Runtime Virtual Office activation/deactivation.

sesnum: Maximal number of simultaneous CTIVO connections toward CTIR [1..255].
volog: CtiVo log events filter at system startup [ERR, INFO, DBG] or [DFT, FULL], where: - ERR, INFO, DBG filters can be joined using "," operator; - DFT: means ERR and INFO events; - FULL: means every type of event.
vologsize: CtiVo log size [20..2000 Kibyte].
CTIP-TYPE: CTIP type assigned to CTIVO driver [USER, NET-PRIVATE, NET-PUBLIC].
PS-NUM: System default postselection number. "#" or up to 20 digits ['0'..'9'] optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] attributes. Omitted TON is set it to 'u', omitted NP is set to 'x'. When "#", the parameter isn't used. See HELP ISDN ATTRIBUTES for details on attributes.
CB-NUM: System default Callback number. "#" or up to 20 digits ['0'..'9'] optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] attributes. Omitted TON is set it to 'u', omitted NP is set to 'x'. When "#", the parameter isn't used. See HELP ISDN ATTRIBUTES for details on attributes.
CB-CGO-NUM: System default calling number used to perform the callback call. "#" or up to 20 digits ['0'..'9'] optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] and/or PI [a, r, m, q] and/or SI [y, v, w, z] attributes. When "#", the parameter isn't used. See HELP ISDN ATTRIBUTES for details on attributes.
CB-AUTO-CDO: Blind Callback. This number is automatically called if the callback call goes active and the no DTMF are received within CB-AUTO-CDO-TOUT seconds. It's also called if the first DTMF received is #. "#" or up to 20 digits ['0'..'9'] optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] attributes. Omitted TON is set it to 'u', omitted NP is set to 'x'. When "#", the parameter isn't used.
CB-AUTO-CDO-TOUT: Blind Callback. Timeout for DTMF reception after which CB-AUTO-CDO is automatically called [0..10 sec].
CB-DELAY: Call Back delay [0..60 sec].
CB-NRTY: Number of Call Back attempts [0..5].
OUTDIAL-DIGIT: This is the prefix required to make external calls. It's passed to Abilisphone for the proper handling of address books. "SYS" or from 0 to to 6 digits ['0'..'9']. When SYS the actual value is taken from OUTDIAL-DIGIT parameter of CTISYS and shown between brackets.
DJ: Default jitter buffer for not-AP-VoIP calls [0..1000 ms].
MJ: Maximum jitter buffer for not-AP-VoIP calls [0..1000 ms]
wdir: Working directory. Full path with drive letter ['C'..'Z'] terminated by '\'. Max 128 chars. Spaces require double quotes (E.g. "C:\My dir\").
ap-channels: Maximal number of simultaneous Abilisphone data connections [0..255].
ap-udp-locport: Local UDP port for AbilisPhone data connections [1..65535].
AP-TOS: Type Of Service octet (rfc1439) or Differentiated Services (rfc2474) for all AbilisPhone packets: -' p-t', i.e. PRECEDENCE and TOS values, where 'p' can be [0..7] and 't' can be [N=None, D=Min. Delay, T=Max. Throughput, R=Max. Reliability, C=Min. Monetary Cost] - 'bbbbbb', i.e. DS value bit by bit, where 'b' can be [0, 1]
AP-IPSRC: Allowed AbilisPhone client's IP address. [*, 1-126.x.x.x, 127.0.0.1, 128-223.x.x.x].
AP-IPSRCLIST: List of further allowed AbilisPhone client's IP addresses [#, IP/IR/RU/MR listname].
AP-AUTH-TOUT: Timeout for an unknown AbilisPhone account to authenticate itself [2..255 sec].
AP-CONN-TOUT: Timeout to check remote connectivity [2..255 sec].
AP-PS-TOUT: Timeout for a requested postselection to be performed to reach directly the final endpoint [2..255 sec].
AP-DTMF-LEN: Duration of a DTMF played on DTMF request [40..1000 msec].
AP-DTMF-SILENCE: Duration of a silence queue after a played DTMF [40..1000 msec].
AP-NOTIFY-HOST: The hostname of the notification service to wake up smartphones with abilisphone installed and allow them to receive a voip call or other call infos. FQDN name of max. 64 characters in the range ['0'..'9', 'a'..'z', '-', '.' ], optionally followed by a port value [1..65535], separated by colon (E.g. host.net.dom:80 or nn.ddd.com). FQDN name is forced to lower case.

Moreover, there is a set of parameters that does not act directly in the Abilis but are relayed to the Abilisphone.

AP-WIFI-DJ

Default jitter buffer for VoIP calls in WiFi [0..1000 ms].

AP-WIFI-MJ

Maximum jitter buffer for VoIP calls in WiFi [0..1000 ms].

AP-MOBILE-DJ

Default jitter buffer for VoIP calls in 3G/4G data [0..1000 ms]

AP-MOBILE-MJ

Maximum jitter buffer for VoIP calls in 3G/4G data [0..1000 ms]

AP-VOIP-CODERS

VOIP coders [G.711, Spirit, G.729A, G.711A, G.711u].

Values can be joined using ',' (comma).

The position in the list defines the preference order.

The rightmost value is the one with the lowest preference.

AP Link Evaluator thresholds parameters to disable VoIP:

AP-MAX-JITTER: Maximum jitter threshold [0..1000 ms].
AP-MAX-JITTER-COUNT: Count of AP-MAX-JITTER to disable VoIP [1..255].
AP-AVG-JITTER: Average jitter threshold to disable VoIP [0..1000 ms].
AP-AVG-RTT: Average Round Trip Time threshold to disable VoIP [0..2000 ms].
AP-MAX-PCK-LOSS: Percentage of lost packets to disable VoIP [0..100 %].

The most parameters are normally kept at the default value.

The following command allows the administrator to change the configuration of the resource:

s p ctivo parameter:value...

	Caution
	To activate the changes made on the upper case parameters, execute the initialization command init res:ctivo; while to set act the changes made on the lowercase parameters a save conf and an Abilis restart are required (i.e. With warm start command).