XC5-XS User Guide

Overview

XC5 is high capacity, fully featured, scalable SIP rfc3261 compliant soft-switch.

• The design targets maximum interoperation, with minimum configuration.
• Flexibility is achieved deploying back-to-back user-agent typology.
• Day to day configuration and provisioning is typically integrated and automated into your business environment portal via the XC5 API.
• This document outlines technical aspects of XC5 - most of which are targeted at the configuration layer beneath the API.

Operation

XC5 implements the majority of features through an account. An account defines an XC5 endpoint, either physical, or virtual.

A physical endpoint represents a SIP endpoint connecting to the XC5 network.

• A REGISTERING SIP User or SIP Trunk
• A Statically allocated/routed SIP User or SIP Trunk, Including Carrier Interconnects, and SIP Gateways

A virtual endpoint represents an element inside the XC5 network

• A Toll Bypass customer
• A delegation route resolver (I.e. _route.default, or a carrier/trunk load sharing element)
• A diversion/distribution point (I.e. Implementation of a Toll Free System)
• Authorization for API access
• An internal service (I.e. The originator account for an outdial test _service.outdial)

Reserved/Common Account names/prefixes

Use of a leading underscore _ for Account names is reserved for organizational and special purpose accounts.

Physical Endpoint Registration

SIP User-Agents can register directly via their account user/password

Alternatively, an account can use an IP address (static) or DNS resolution to send an OPTIONS probe to verify the connectivity status and fabricate an endpoint Registration.

This fabricated registration authorizes ingress calls by IP address.

Ingress / Egress Call Perspective and Flow

As nearly every call enters XC5 for processing, then is delivered to it's destination, we refer to a calls direction from the perspective of XC5 (Your network)

• Alice is registered to XC5 and makes a call

XC5 receives this call as an ingress call, and assuming Alice has authorized, the context of Alice's XC5 Account is used

This is XC5's hop_type from_user. The call is "from_user":"alice"

Alice's AccountResources are considered, allowing variation to the handling of the call

Ingress normalization / numbers translated to e.164. "Inward number translation"

Alice's Account Numbers used for ingress validation/caller screening

Account Call Rules are considered, allowing dial plans, changes to privacy, resource overloading, router nomination, concurrency limits and other features to be imposed

SmartPhone/DialCode features are processed

• Once the account has finished applying these features, XC5 determines a new outgoing account context to service the destination

If the destination number is assigned to another XC5 account, then that account will be used

If no account exists with the destination, then the default_resolver setting will specify the account to be used to service the destination

The default resolver may specify a routing table. The routing table operates similar to sending calls out a regular endpoint account, and can conditionally delegate to other accounts

• XC5 now operates within the context of this outgoing account. Let's assume Alice dials a destination that does not belong to a local XC5 account. The default_resolver is unchanged so we use the account _route.default

AccountResources are considered

AccountRoutes below 0 are considered (negative account routes)

Account registration is considered. _route.default doesn't have any accountreg or endpoint data, so no attempt is made to call an endpoint

AccountRoutes above 0 are considered (positive account routes)

If Alice dials 6421123123 and _route.default has been configured with an Account Route that delegates to _Carrier.Vodafone based on criteria:Destination Location("NZ - VFNZ"). This route criteria would be satisfied if the LocationName("NZ - VFNZ") contains a LocationCode with a prefix of 6421 - or even more specifically, the LocationName could contain all Vodafone LMNP ported numbers, which may include 6421123123

Lets assume the route satisfies the condition so XC5 delegates further processing of sending the call to the account _carrier.vodafone

• XC5 now operates with the context of this outgoing account - _carrier.vodafone

AccountResource are considered

AccountRoutes below 0 are considered (negative account routes)

Account registration is considered. _carrier.vodafone has a fabricated registration with contact address due to outgoing OPTIONS probe

"Outward number translation" logic is conditionally performed on caller/called/diverting numbers

XC5 sends this call as an egress call to the vodafone endpoint. This is XC5's hop_type to_user. "to_user":"_carrier.vodafone"

Consider 6421123123 is now making a call attempt to Alice, the flow is essentially the same:

• In NZ, Vodafone knows via either Number Administration deed (https://www.nad.org.nz/), ipms/LMNP (tcf.org.nz), or PNCA agreement, that Alice is on your network so sends the call to your XC5 interconnect

XC5 receives this call as an ingress call. This is XC5's hop_type from_user. "from_user":"_carrier.vodafone"

• XC5 locates Alice (perhaps by assignment of a phone number to Alice's account)

XC5 sends this call as an egress call to Alice. This is XC5's hop_type to_user. "to_user":"alice"

Setting up a User

Create an account for the user

• username/password

The username must be unique over the entire system

For sip registering accounts, this is the username and password used for authentication. A subscriber (I.e.6412341234) who registers using their phonenumber as their username may also be added as _tel.6412341234. This removes the need to create an AccountNumber entry, as xc5 location services will consider a user of _tel.6412341234 as the owner of the number 6412341234. Note: It is advised to avoid using a publicly known phone number as a username.

For carrier accounts, this is the name of the carrier entry

For Whitelist ddi accounts, the _tela. and _tel. prefix can be used to indicate this user is an a or a+b whitelisted customer

usernames commencing with _tel.nnn will allow nnn to be used for both A whitelisting and B whitelisting (target resolution)

usernames commencing _tela.nnn will allow nnn to be used only for A whitelisting

usernames containing an @ i.e. 700@xyz.com will allow the location service to locate the dialed number within the same domain. I.e. 700@xyz.com can dial 701, which will locate user 701@xyz.com

It is recommended to create wildcard DNS records to the user/public facing xc5 nodes on your network. Using an example wildcard domain *.xc5.expresscall.co.nz, A user created as alice@acmebricks.xc5.expresscall.co.nz, Allows alice to REGISTER as username(alice) to acmebricks.xc5.expresscall.co.nz, Allows alice to REGISTER as username(alice@acmebricks.xc5.expresscall.co.nz) to the ip address of the XC5 nodes, supports devices that authorize using their phone numbers. username(641231234@xc5.expresscall.co.nz) will allow the user-agent to authorize as 641231234 if they register to xc5.expresscall.co.nz

• For multiple DDI's (SIP trunking) or accounts where the username doesn't specify this users phone number, Add the DDI for this registration to the AccountNumbers section.

The numbers must be in e.164 format (start with the country code, I.e. 6412341234).

AccountNumber table allow multiple DDI's per user

A DDI/AccountNumber cannot be assigned to multiple users. To share a number, multiple devices should add additional lines to register as the same username, whereby calls to the DDI will be forked to all registered usres.

This user will be allowed to present any number assigned in their AccountNumber table (See caller_control). To allow a user to present a number which they do not own, the number can be added with the a: prefix. Numbers with the a: prefix can be assigned to multiple users.

• AccountResource:nature_of_address : This will default to UNK. This is the recommended value. : If the user has a different number format, it can be specified here, and implemented in the TranslateNumber section

nature_of_address value	Description
int	international, e.164 format. The translate number table will not be used
unk	unknown. This is the default format given to endpoints/users. The number translation tables will be used and the pack noa(unk) can be used to apply translation.
<user_value>	a user defined value. Specifying a user value of nature_of_address will apply the Translation tables with the pack noa(<user_value>) This allows custom translation types

• AccountResource:caller_control=asserted : defaults to asserted

caller_control value	Description
asserted	The caller, or in case of a diversion - the user specified in a diverter/referred-by header must be in the range of accountnumbers assigned to the account. Note: This is the safest of the caller_control settings. If caller control is not asserted, then a compromised endpoint would be able to successfully make calls from any calling number. Note: The accountnumber is used for both calls from the user, "caller screening" and calls to the user "location of the called party". A number may be added with the a: prefix to allow the number to be used only for caller screening.
invalid_pan:1234	If the caller is not in the range of accountnumbers assigned to the account, then use 1234 as the caller
*	Must be set for carriers and routing entries. The caller will not be validated. Not recommended for regular users
forced:12345	Regardless of the presented caller, or assigned numbers, the caller will be forced to 12345. This replaces the Pilot account resource type

• AccountResource:ivr_account=nnn : If username is _tel.nnn or _tela.nnn, then it is assumed nnn is a number and nnn will be used as a default

It is recommended that users created for the purpose of caller whitelisting (I.e. TBNCA) be created in the format _tela.nnn

For ivr administration login and prompt naming, a numeric account number is required. If the username is not numeric (I.e. does not start with _tel) then the AccountResource:ivr_account can be used to specify the numeric accountnumber

• AccountResource:ruri_method=normal : defaults to normal : Set to called for Registering SIP Trunking devices.

ruri_method value	Description
normal	This is the default. The INVITE sent to the registered customer will be sent direct to the Contact header of the REGISTER
called	The URI taken from the Contact header of the REGISTER will have its user_parameter replaced with the called number. <user_parameter>@someaddress.net.
lmnp_npdi	This tag enables rfc4694 : Number Portability Parameters for the "tel" URI - for calls to LMNP ported destinations. This requires a populated LMNPRoute table

Note: For SIP Trunking, If the registering UAC implements rfc6140 (bnc tag). The RURI will be formed in accordance with rfc6140 : The ruri_method is not required and will be ignored.




Note2: By default, the SIP To: Header will contain the CALLED number. Allowing SIP Trunking. However devices that only inspect the RURI header, will need ruri_method=called.




Note3: Setting ruri_method=called for non-SIP Trunking devices can cause regular user-agents to ignore incoming calls.

• AccountResource:outgoing_tags : Configures various settings for outgoing calls

outgoing_tags value	Description
answer-reinvite	After call establishment, a reInvite is sent. This has been used in the past to fix user-agents that change their SDP between 183 and 200. In violation of https://tools.ietf.org/html/rfc3261#section-13.2.2
domain:example.com	This rewrites the host part of the RequestURI to 'example.com'. XS normally resolves DNS lookups to IP addresses and the IP address is included in the host portion of the RequestURI.
local-domain:example.com	The local domain is usually taken from system configuration. This specifies a specific local domain for use in host portion on From headers
no-t38	Strips sending any t-38 media from SDP on Initial-Invite
secure	Offers RTP/SAVP then RTP/AVP to endpoint
secure_only	Offers only RTP/SAVP to endpoint
x-route:tag	Includes x-route tag into Via for various Cisco/PGW deployment

• AccountResource:default_resolver=_route.default : For outgoing calls from this account, and where the destination (called number) does not exist on the local system, The account will delegate each call to the specified default_resolver.

Overriding the default_resolver allows Source Routing and Class of Service Routing

Apply PIN for International only

• Ensure the user has a PIN created on their account

If a single PIN is required, then the pin may be added directly in the Account's PIN field.

If multiple PIN's are required, then the Account's PIN field must contain the value M, and the pins must be added under the AccountPIN table

• Create a callrule to ignore the PIN for National calls. NOTE: PINS normally apply for non-local calls

Applying privacy for a single DDI

• Create a callrule

Forcing PIN instead of destination blacklist

• If <Destination Blacklist> is populated, by default calls will not be allowed. To switch from blacklist to pin
• Create a callrule

Extension dialing

• Available for users created with a domain in their Authorization User. I.e. An XC5 account: 700@xyz.com can dial 701 to call an XC5 account who is authorized as: 701@xyz.com

Setting up a Carrier interconnect (Static ip)

Create an account for the carrier

• username _carrier.<carrier>
• If the carrier is not going to REGISTER, leave the password empty
• AccountResource: endpoint_ip_address=0.0.0.0

specifies the carriers ip_address for inbound and outgoing routing

for multiple source addresses (inbound only) multiple endpoint_ip_address entries can be created with the in: prefix. I.e. endpoint_ip_address=in:1.1.1.1

for multiple destination addresses, equal (time-load-shared) addresses or DNS entries may be specified using +, and second choices can be separated using a comma(,). The out: prefix specifies these address are only for outgoing calls (to the user). out:1.1.1.1+1.1.1.2+1.1.1.3,1.1.1.6 will load shared over the first 3 addresses, then fallback to the fourth. The discovery_method must be either probe or resolver.

For infrastructure accounts, discovery_method defaults to 'probe', for non-infrastructure accounts, the discovery_method defaults to 'endpoint_ip'

For endpoints with discovery_method='endpoint_ip', upon receiving an INVITE from the endpoint, the AccountResource:endpoint_node is updated if required, to automatically create a symmetric return path. NOTE: The endpoint_node is changed automatically to the node that received an INVITE. If you manually change the endpoint_node, your change may be overwritten.

Use xs_node_group/endpoint_node_group to specify a list of nodes. This constrains DNS/probe discovery to specific nodes. Use net_bind_listener to constrain probes to nodes with the specified network listener created

NOTE on sharing the same endpoint_ip/connection combination amongst multiple carriers. If _carrier.a is configured and can see 1.1.1.1;con=general from node1, and _carrier.b is configured and can see 1.1.1.1;con=general from node2, Then both _carrier.a and _carrier.b will use both nodes. If you need disjoint peering, create a new network listener/bind for each carrier to constrain the discovery to specific nodes/networks

• AccountResource:default_resolver

If not specified, _route.default is assumed. This means calls from this carrier, which are not located within xc5, will be routed by _route.default. Allowing wholesale re-routing (Potential Hairpin)

Recommended: If this carrier/interconnect is designed to receive calls for the local network only, change default_resolver to _route.onnet_only. Create an infrastructure account for _route.onnet_only and add an AccountRoute to release the call, I.e. drop:404:Unallocated Number

• AccountResource:nature_of_address

nature_of_address value	Description
int	international, e.164 format. The translate number table will not be used. This is the default for internal xs call switching
unk	unknown. This is the default format given to endpoints/users. The number translation tables will be used and the pack noa(unk) can be used to apply translation.
<user_value>	a user defined value. Specifying a user value of nature_of_address will apply the Translation tables with the pack noa(<user_value>) This allows custom translation types

• AccountResource:privacy_policy trusted : For anonymous calls, this allows us to disclose the privacy information to the upstream carrier. : Privacy information must not be disclosed to end users, but should be delivered to upstream carriers

privacy_policy value	Description
trusted	For anonymous calls, this allows the Privacy caller to be sent to the endpoint
<other values or not specified>	Privacy callers will not be disclosed to the endpoint

• AccountResource:caller_control=* : defaults to asserted.

caller_control value	Description
asserted	The caller must be in the range of accountnumbers assigned to the account. Non-owned numbers may be added to the AccountNumber table with the a: prefix. This avoids the location service, yet allows the caller to present the phone number
invalid_pan:1234	If the caller is not in the range of accountnumbers assigned to the account, then use 1234 as the caller
*	Must be set for carriers and routing entries. The caller will not be validated
forced:12345	Regardless of the presented caller, or assigned numbers, the caller will be forced to 12345

• AccountResource:lmnp_network

If this network is participating in LMNP routing (lmnp hoc added using number translation), then set the lmnp_network to the network names of the carrier

This allows the LMNP_IS_DESTN(1) condition to be used in outgoing number translation to avoid sending the carriers own HOC to the carrier

The outgoing number translation can have rules, translate_from(%)translate_to(${lmnp_hoc}%)where(LMNP_IS_DESTN(!1))

• AccountResource:trunk_identifier : Specify a method and value to represent a target trunk

trunk_identifier value	Description
tgrp:abc	Targets "abc" using rfc4904 tgrp within request uri
x-route:"cid:VF-AK@1.1.1.1"	Sets topmost via x-route
x-nortel-profile:abc	Sets abc in nortel-profile header

• AccountResource:codec_policy

codec_policy value	Description
default	Calls to the user will use codecs offered by the caller
force:alaw,mulaw	The force prefix forces the following codec list on calls to the user. Native codecs are alaw,mulaw,g729,iLBC
expand:g729	Expanding will add the codec list to the codecs offered by the caller

• AccountResource:concurrent_call_limit : Specifies the maximum simultaneous number of calls in/out/otherwise for this account. (cac_limit)
• AccountResource:inherit_account : Specifies the account (template) that additional settings will be inherited from

accountresources will be used from the template account, and will be overwritten by resources of the local account. (Read as, the local account's resources take precedence over the templates resources)

For accountroute and accountcallrule, The rules will be MERGED.

• AccountResource:fs_data : Provides configuration tags to callcontrol processing. Delimit multiple tags using ,

fs_data value	Description
answer-reinvite	Issue a reinvite upon the call connecting
dtmf-rtp-event	If the caller didn't offer rfc2833, XC5 attaches a tone detector to the callers rtp and INVITEs the trunk with telephone-event / rfc2833 enabled
inband_to_rfc2833	When calling the trunk, and regardless of rfc2833 offered from the caller, XC5 will use a tone detector to generate rfc2833 events to the trunk when receiving inband dtmf from the caller
no_caller_id	Specifies even non-private calling party number should not be passed to this trunk
no-screened	Clear the Remote-Party-ID screened value to allow privacy=off to work with some international carriers
use_referred_by	Switches from diversion to Referred-By header
send-session-id	Allows delivering session-id to upsteam interconnect

• net_bind_listener

If traffic to this interconnect must emit from a specific source address/interface, net_bind_listener must be set to the name for which the listener config is specified within ysipchan.conf

I.e. If carrierX exists on the network for which our address is 10.1.1.1, then

Set net_bind_listener=carrierX

Provide the following configuration in ysipchan.conf

[listener carrierX]
type=udp
enable=yes
default=no
udp_force_bind=yes

;local address to bind to
addr=10.1.1.1

; rtp_localip: ipaddress: IP address to bind local RTP to, empty to guess best
rtp_localip=10.1.1.1

Default routing

• When calls are routed, XC5 checks to see if the destination (called number) exists in an Account/AccountNumber table.

Situation	Outcome
If adding the _tel. prefix to the destination matches an AccountName	The Account/User is contacted directly on their host nodes
If destination exists as an AccountNumber (Belongs to an account)	The Account/User is contacted directly on their host nodes
If hoc_locate pack (via number translation) has been provided, and the hoc_locate value exists as an AccountNumber (Belongs to an account)	The Account/User is contacted directly on their host nodes
If destination does not exist as an AccountNumber	The reserved Account/User _route.default will be used. An account can provide an alternative for _route.default using the default_resolver AccountResource, or callrules/routes

• A router is implemented using an account with an AccountRoute table containing delegations.
• An account is created during installation for the default routing resolver: _route.default

Accounts may override the default_resolver, or delegate routing to another custom account. I.e. for class of service routing

• For the applicable account (I.e. _route.default) (think of the account as a routing table), Add Account Route entries to conditionally delegate to the _carrier account that the call should be sent to.

Field	Description
E.164 Destination	Leave this empty. This is used to implement a diversion rather than a route
Delegate User	If all route conditions are satisfied, Then routing will be delegated to this account. The delegated account can perform further routing steps, or implement the delivery to an interconnect
PackModifiers	Leave empty, this can be used to push pack variables to delegates or specify additional attributes for interconnects
Hit Counter/HitWeight	specify a hit weight of 1. Each time this route is chosen, hit weight is added to hit counter.
Priority	Routing choices are made based on lowest priority, then for equal priorities, the lowest HitCounter. this allows load distribution (Similar to DNS SRV records)
Time of day	If specified, the time of day must match for this route to be eligible
Dest Location Name	If specified, the called number must belong in the specified location name for this route to be eligible
Orig Location Name	If specified, the calling number must belong in the specified location name

• Refer to the AccountRoute documentation for additional details

• Required pack : Various call control values are available for which to perform a conditional test (See the Pack Matching section)

Required Pack Value	Description
TAN(<caller>)	The (e164 translated) caller
TBN(<called>)	The (e164 translated) called
TDN(<diverter>)	The (e164 translated) diverter
LMNP(0)	The TBN is not lmnp ported
LMNP(1)	The TBN is lmnp ported
LMNP_HOC(<hoc>	If LMNP(1), The network hoc the called party is ported to
LMNP_N(Carrier>	If LMNP(1), The carrier's network the called party is ported to
LMNP_C(Carrier>	If LMNP(1), This specifies the carrier the called party is ported to
A_*	ALL the above LMNP fields can be prefixed with A_ to refer the the LMNP status of the calling party, I.e. A_LMNP(0) : The TAN is not lmnp ported
CALL_DATE	The current date/time. Can be used to conditionally apply time of day. $time:CALL_DATE(Mon-From 08:00-17:00)
LMNP_IS_DESTC(1)	Set if LMNP_C=(AccountResource lmnp_destination). This is useful for number translation hoc addition/removal
LOCAL_AREA(1)	The caller and called parties are within the same Minor-Lica
B_NEVERBLOCK(1)	The TBN is in the <NeverBlock> locationcode
B_NEVERBLOCK(0)	The TBN is not in the <NeverBlock> locationcode
Response(<sipcode>)	The sip response of the previous attempt. I.e. Response(486)

• As _route.default is generally used to locate routing destinations for calls that are not found on your local network, there is a possibility a number is known to belong to your network, but just not currently allocated. Create routes to avoid routing unallocated numbers that belong to your network

Description	Destination	Required Destination location	RequiredPack
Local network owned in NAD, and not outported to another network	drop:404:Unallocated	NZ-NAD-Carrier-LocalNetworkname	LMNP(0)
Calls that have been LMNP ported to local Carrier	drop:404:Unallocated		LMNP_C(LocalCarrierName)

• TBNCA is implemented through HOC sripping in accountcallrules

The impersonate tag must be set in callrules:packmodifier, providing: impersonate(${diverter}). Note: The system/callrules will use the caller as the diverter

The TBNCA accounts 'AccountNumbers' must be added with an a: prefix. (Or the account may be a _tela. prefixed account). The impersonation will then find the AccountNumber, but it will not be detected as a b number

The impersonate rule indicates location routing is performed on the modified diverting number (Which is the caller if no diverter is present). The a: AccountNumber prefix, and _tela. account prefix stops b location services from locating this destination, but the origination is located on a:NNNN (where NNN is the caller)

The callrules:packmodifer can specify the optional parameter: not_found(<username>). If an impersonation fails to locate the impersonated accountnumber, it will attempt to delegate/route to the user specified in the not_found parameter. This user can be customized to provide a prompt: AccountRoute to destination drop:404, with packmodifiers: prompt(generic/xc5_nu_tone.auto)

• Outgoing calls to destinations that are not in the local system will use the delegate use _route.default to resolve the terminating carrier
• User AccountRoutes can make use of "delegate user", instructing the routing logic to be delegated to the specified user. The called number would generally remain untouched (unless for reason it has been modified as above, however the process is still considered a delegation rather than a diversion)

Pack Matching

• NOTE: Pack names are CASE SENSITIVE
• Satisfies the pack match if the field "field" has the value "value"

field(value)

• % and _ can be used for wildcard matching. Match TAN starting with 64

TAN(64%)

• Multiple entries represent a logical AND, ie. If Both A and B numbers start with 64.

TAN(64%)TBN(64%)

• Order is not important

TBN(64%)TAN(64%)

• Inverse/Logical NOT, matches if TBN is not starting with 64

TBN(!64%)

• $location:<field>(<spec>) Can be used to match LocationNames for translated A,B & D numbers.
• $time:<field>(<spec>) Can be used to match TimeDefinitions and regular weekday/time ranges

Pack Modifiers

• Allow introducing or replacing pack values

Call Rules

Call rules allow implementation of call readdress

• Applied when this account is asking to make an outgoing call
• Applied when this account is diverting and subsequently making an outgoing call
• Applied in the order of priority/hitcount
• Will apply according to criteria - RequiredPack, RequiredBNumber, Required Destination Location
• Applied consecutively whilst the destination (new number) is empty, OR the callrule_continue(1) Pack Modifier is specified
• If a destination is set and the callrule_continue(1) pack modifier is specified, The new destination will then be used to match the 'Required B Number' for subsequent call rules. The TBN will remain unchanged - unless explicitly set in the Pack Modifiers.

Forcing A Destination Whitelist to offnet

• Set the default_resolver to _route.null
• Add a callrule for the acceptable destination location to clear the default_resolver

An example of conditionally applying validated multiple PINs

• Multiple PINs may be added into the AccountPIN table

Each PIN may include pack formatted data, I.e. Pin=1234, Pack=user(bob)

• If the AccountPIN field in the Account is empty, no PIN will be requested, regardless of the fact there are PINs in the AccountPIN table
• A callrule may be added for specific destinations or criteria to conditionally enable the multiple PIN feature

I.e. For Required Destination Location <Expensive Destinations>, we can add a Pack Modifier for pin_force(M)

This conditionally will act as if M was in the Account.AccountPIN table, and activate the multiple pin functionality for calls to numbers in the <Expensive Destinations> Location

• cdr is written with the cdr_pin and cdr_pinpack attributed to the PIN used.

The CDR consumer may extract the user value from the cdr_pinpack to include on a call record.

Account Routes

AccountRoutes

• Are applied in the order of Route Order
• Apply conditionally according to settings, Active, Origination Location, Destination Location, Required Pack values
• Upon a calls first entry into an accounts accountroute table, the menu pack value will be set at 1
• Pack modifier digit_maps can target menu levels by routing to #n - where n is the new menu. I.e. #3 will set menu(3) which can then be used to conditionally apply a different digit_map
• Re-routing / follow_on

If a route attempt fails, the response value will be set. I.e. response(486)

For destination routes, routing will not process any further routes. follow_on_codes defaults to (nil)

For delegation routes, routing will progress on responses 5xx,6xx,480,488 and 408. follow_on_codes defaults to (^[56]|480|488|408)

The follow_on_codes pack modifier can specify a regular expression of codes that will cause routing to continue. I.e. follow_on_codes(408|^5) will allow routing to proceed on a 408, or any 5xx code.

A remote response code may be translated by specifying a pack modifier of response_remap. response_remap(486=503,408=500). 503 is internally remapped to 500.

The final_route(1) pack modifier indicates that if this route is eligible, no further route attempts should be attempted after this route attempt (FOR THIS HOP). This is the same as follow_on_codes(nil)

Common Diversion Types

Available pack modifiers

digit_maps - A pack modifier that specifies a , separated list of digit=destination mappings. When a digit_map pack modifier is applied, call control will

• answer the call
• play a prompt

c:\programdata\designcom systems\prompts\customer\${ivr_account}_${menu}.slin

The prompt may be recorded using the admin ivr (route to destination admin_ivr:_prompt.shared:prompt::)

The customer directory must be DFS shared over multiple machines

• collect the least amount of input/dtmf digits necessary to satisfy the longest applicable 'digit' part of the digit=destination mapping

. can be used in the digit specification to match any digit. Each . specified within the destination will be substituted with the wild card matched . in the digit part.

• route to a new destination as specified in the destination part of the best matched digit=destination mapping

Special digit of the digit=destination mapping

• E= will match all/else/error if no other digits applied
• 1T= When the digits timeout, T will be appended to the digit match.
• T= Action to take on dtmf timeout
• .= A placeholder to match any character

Destination of the digit=destination mapping

Example digit_map usage in AccountRoutes

Implementation of existing xc5 Location-First Routing

• Rather than routing by routeorder first, existing xc5 first, reduces the route set to only routes having a locationname with the longest matching locationcode. It also will still include routes for null destination locations.

The set is 'reduced' to only the best fit destination location, or entries with no/null required destination location

• Route-order is then used to order the set
• To enable Location-First Routing the Account:Pack must have the value: route.strict_location(1)

Implementation of existing xc5 Class of service

• An account wishing to apply COS should set it's AccountResource:route_criteria to the text name of the class of service
• Routing can still proceed/delegate to any resolver (I.e. route.default) The route resolver can then conditionally use the route_criteria in the Required Pack of each route.
• Regular routes (without a required pack) will still be selected as valid route choices. (This is the xc5 allow_default_route=true setting)
• To disable using regular routes (allow_default_route=false), an account entry must exist _cos.<route_criteria>. With the Account:Pack value route.criteria_required(1). This indicates to routing, that the route_criteria entry must be present and match to be selected

Implementation of hunt groups

• Setup Account Routes to delegate to each member
• Use RouteOrders between 100 and 200 to isolate the feature
• For round-robin use same route order
• For Sequential hunt use incrementing route order
• To avoid following destination routes for the delegated members, Include route_criteria(xs:regonly) in each AccountRoute:PackModifier
• To specify a ring/no-answer duration i.e. 20seconds, Include cfnaduration(20) in each AccountRoute:PackModifier

Load sharing across multiple carriers (with fall-back)

;Conceptual route plan
plan1 -> carrier1, carrier2, carrier3
plan2 -> carrier2, carrier3, carrier1
plan3 -> carrier3, carrier1, carrier2

;Route 1 tries one carrier then sets route_data value forward
route 1 delegate(_carrier.1) hitweight(1) packmodifiers(route_data(use:plan1))
route 1 delegate(_carrier.2) hitweight(1) packmodifiers(route_data(use:plan2))
route 1 delegate(_carrier.3) hitweight(1) packmodifiers(route_data(use:plan3))

route 2 requiredpack(route_data(use:plan1)) delegate(_carrier.2) 
route 2 requiredpack(route_data(use:plan2)) delegate(_carrier.3) 
route 2 requiredpack(route_data(use:plan3)) delegate(_carrier.1) 

route 3 requiredpack(route_data(use:plan1)) delegate(_carrier.3) 
route 3 requiredpack(route_data(use:plan2)) delegate(_carrier.1) 
route 3 requiredpack(route_data(use:plan3)) delegate(_carrier.2) 

Prompt Management

• User accounts may host their own prompts
• System-wide (Shared) prompts can be maintained within the reserved _prompt.Shared infrastructure account
• _prompt.shared can be configured to allow IVR entry to the administration recording IVR
• To enable a system-wide prompt recording/management IVR

Configure an AccountRoute for a RequiredDestination number/ddi allocated to the account

Configure the AccountRoute destination: admin_ivr:_prompt.shared:prompt:

Add a secure pin to the _prompt.shared account. A secure PIN must be prefixed with S. Example: S1234

• A DDI can also be configured in _prompt.shared to allow IVR access for personal account use

Configure an AccountRoute for a RequiredDestination numer/ddi allocated to the account

Configure the AccountRoute destination to: admin_ivr. Set other pack modifiers to: ivr_action(prompt)ivr_account(${TAN})

This will allow the calling party number to administer prompts for their own account

Ensure the calling party number as a secure PIN configured.

A secure PIN is an AccountPIN commencing with the letter S. I.e. S1234

The S is not required to be entered within the IVR

• _prompt.Shared can also implement the user Diversion IVR

Configure the AccountRoute destination to: admin_ivr. Set other pack modifiers to: ivr_action(diversion)ivr_account(${TAN})

Star Codes / Smart Codes

• Smart Codes are disabled for probed accounts (Implied as a trunk). It can be enabled with an accountcallrule requiredpack=early_rule(true) packmodifers=smartphone(true)
• Smart codes are preset features accessible from your phone
• Your phone or its dialplanner may intercept dialing the * prefix for its own use.
• You can create a speeddial to translate another number I.e. A speeddial mapping 14 to *% will allow you to use 14 as the * prefix
• You may want to use a different dialplan to access the Smart codes. You can create a speeddial to translate your dialplan into the standard smartcode prefixes

Fraud

• The fraud mechanism applies for connected calls to locations specified in the <Expensive Destinations> location. Too many calls to these destinations will be considered fraud
• The accountpack can override the default fraud configuration: expensive.consume(240). expensive.consume specifies a distance in seconds each fraud call consumes. Fraud is triggered when the cumulative distance exceeds 900 seconds (15 minutes).
• (2023-09 Update) Infrastructure Accounts disable fraud by default, unless expensive.consume is manually specified
• If you need to disable the fraud mechanism completely, you can set the account pack: expensive.consume(0)
• When the threshold has triggered, the default_resolver is changed to _route.fraudblock
• _route.fraudblock should be configured to allow emergency services, and possibly your callcentre.
• Calls to numbers within your network are still allowed. (The default_resolver isn't used for on-net destinations)
• A alarm email is sent
• The fraud trigger will naturally age, so to unblock a fraud locked account, remove the resolver entry for_route.fraudblock

Spam

• Excessive short duration calls will be considered SPAM and will automatically create a callrule (at -14) to block calls from the caller.

The rule does not apply to emergency services calls as it is ignored for numbers within the <Never Block> locationname group

The rule is set to expire within a 10 minute period

Calls subjected to the rule are released 404:Not found-OL

AccountResource:short_duration_trigger can override the max() and period() settings

max(20) specifies the maximum number of short duration calls allowed within the period(60) of seconds before the rule will be created

AccountResource:short_duration_trigger max(0) will disable the short duration logic for the account (All callers of the account)

The short duration rules apply only to the specific caller within the account - useful on carrier interconnects

If no common caller exists or many short duration calls continue after blocking the specified caller, an alarm will be raised. The offending carrier/account should be investigated/contacted regarding the excessive short call volume

Plugins

Plugins allow IVR or enhanced functionality.

• A plugin can be conditionally applied within a call rule or a route by specifying the plugin name as a new destination.
• Plugins may be customized for your network

• IVR login: Some plugins require IVR login. The user dials their phonenumber and xc5 locates the account for the phonenumber searching the translated number in the following places

Accounts with the ivr_account account resource. I.e. 123123123 would locate and account with AccountResource:ivr_account=123123123

Accounts with the _tel. prefix. I.e. 0800123123 would match _tel.64800123123 : Uses Inward B Number translation with pack noa(unk)module(ivr)

Accounts containing the phonenumber. I.e. 0800123123 would match AccountNumber 64800123123 : Uses Inward B Number translation with pack noa(unk)module(ivr)

• IVR PIN: IVR login requires a SecurePIN. A secure PIN is an administrative pin. Regular AccountPIN's and the Account:PIN fields are not used for SecurePIN validation

Add an accountpin by prefixing the PIN with S. I.e. S1234 would allow 1234 to be used as a SecurePIN

• Restricting the admin_divert destinations

As the dialed destination is subjected to Inward B number translation, we can impose restrictions on the allowable destinations

Example Number Translations to only allow diversion to NZ and AUS

Number translation

The XC5 system requires and stores all internal numbers natively as INT/e.164. For ingress calls, number translation is used to cast calling/called/diverting numbers to e.164 format, and for egress calls, number translation is used to cast calling/called/diverting number for e.164 to the required destination format.

An account can specify a Nature of address (noa) tag. This tag is used as a conditional to apply the Number Translation table.

• Ingress calls: The noa will be taken from the authorized callers accountresource(nature_of_address). If not specified, UNK is the default. (unknown)
• Intra-XS ingress calls are marked as noa(INT) on the call to FeatureGet_A (International, e.164)
• Intra-XS egress calls are marked as noa(INT)
• Egress calls will use the accountresource(nature_of_address), with a default of UNK

Field	Description
Priority	Only the first matching translation of the lowest priority value will be used
Match Prefix	A prefix to match. I.e. A prefix of 64 will match number, 641234
New Number	If the prefix matches, This must specify the entire number to translate to. % may be used to represent the 'prefix stripped' remaining part of the number. A new number string starting with $ allows a regular express syntax for the translation $011(...)(.*)=64$2,hoc_locate(6411$1) will turn 0112372222 into 642222 and introduce a hoc_locate value for wildcard/hoc account location
Type	Number translation is performed for each inbound and outbound of the A,B and D numbers. This type indicates which direction and number this translation applies to. I.e. for Inward A, the prefix will match and translate the A number for calls entering the XC5 system
A/B Location Name	The translation will only apply if an e.164 translated A/B nubmer is available the A or B number has a prefix match within the specified locationname
Required Pack	If specified, this translation will only apply if this call contains values specified in the required pack

Accounts may also utilize the AccountResource:translation_map to perform early inward and outward translation. This is useful for remapping smartphone star codes, removing account specific HOCs etc.

Each type of translation (inward/outgoing a/b/d) can define a translation map to apply. The translation_map for inbound translation is applied prior to smartphone (* codes) and prior to noa/Number Translations. Usual Number Translation is still applied if applicable.

• A translation map specifies a , separated list of matches/translations to perform
• Each , delimited match is tested in order from left to right. The first match found will be used. Matching is done by prefix. To match a whole string, the match pattern must be terminated with $.
• A match can contain an optional rewrite/translator. % can be used in the rewrite translator to reassign the wildcard matched component back to the rewritten number.

Example inward b translation map for smartphone remapping:

ib(*2=*98,*3=*97%,*4,*=drop:404:Not Found)

Location Names

Location Names are used to organize many numbers into manageable groups (Locations). Subsequent functions then use the LocationName as an alias for the collective numbers within.

Reserved LocationNames are placeholders for specific internal functions

• <Never Block> LocationName

If the called destination is within the <Never Block> location, the following functions will be forced

Any required PIN will be removed

AccountCallRules will still be used (Different from previous XC5 implementations)

• <PIN Local Allow> LocationName

If the called destination is within the <PIN Local Allow> location, the call will be treated as a local call.

Candidates are 64800xxx where a toll free destination would not require a PIN

If a pin is required, it will only be requested for non-local-calls

The pin_force_local accountresource can be set to 1, to require a pin for all calls.

The pin_bypass(1) flag can be set within accountcallrules to avoid pin.

A local call is detected if the calling party and the called party have the same locationname.areacode

Concurrent call limiting

• concurrent_call_limit : Specifies the limit (uses the qualified sum pack value: cac)
• concurrent_call_group can be used to link concurrency counters between accounts. The concurrent_call_group MUST be a valid xc5 account. It requires tracking the nodes that group members have visited
• Accounts using a concurrency setting build the account pack's cac flag as an indicator that concurrency qualification data must be collected on a per call basis.
• The Account pack nodelist provides a list of visited nodes, from which concurrency data will be collected.
• Counters are built and can be used in conditional routes/rules
• Counters can be conditionally changed or sub-partitioned using callrules/routes by changing the default cac_tag

Node Groups

A Node is an XS switching node

• Infrastructure accounts prefixed _node. are configured to share the same node_group name when they share the same networking infrastructure / topology; they have access to the same networks.
• nodes sharing a node_group MUST have access to the same primary/secondary database pair for registration access. (Can be secondary/primary also)
• _carrier entries and those sending option probes can be restricted to a node group
• A roaming user cannot register on both internal and external as the same account
• Subscriber registration to a node will automatically set the node_group to the same group as the node they register to.

It will also set the endpoint_node to further bias the routing to the exact node they registered to

• B node location will use

1: endpoint_node if specified and up (Historical code - could be removed

2: self if self's nodegroup is same endpoint_node's node_group

3: any up node from node_group order by time%60

4: self

1252 xs_node_group

• Applied to _node: Identifies _nodes sharing same network accessibility : Nodes must ignore node_group when probing each other
• Applied to account:

Restricts probes to the node group

1483 endpoint_node

• Applied to account:

Identifies/Locates the node that a single call or registration occurred against

Forget and escalate to node_group? For devices that only accept single server, have a _node that does not belong to a node_group Assume xs_node_group(node_name)

Billing

• Use /api-sys/cdr to extract CDR

For each CDR, add a charge to the accountguid/accountname.
    For hoptype's ["from_user","divert"], you will charge the user for making a call to the destination
    For hoptypes ["to_user"], you will charge the user for receiving a call. (For onnet customers this would be 0 rated, except for tollfree calls (64800,64508) which would be rated based on caller. For carriers, you would charge based on the interconnect arrangement

We suggest assigning two (calling and called) rateplans to each user. For a carrier, the calledrateplan could potentially have a negative charge which indicates the credit to the carrier - used for carrier reconciliation.

Care should be taken to ensure tollfree 0800/0508 and premium rate 0900 numbers are considered individually for carrier vs regular use rateplans

Multi-tenant branch based configuration

• Use call rules conditionally impersonate other accounts

Requires consideration of the interconnected endpoint's capabilities

Call rule conditional on an indicator: HOC / SIP field / rfc4904

Requires to trust the endpoint does not spoof the indicator

• Accounts support direct impersonation of "child" accounts

Parent account holds the location information (registration/endpoint ip etc)

Calls from the account impersonate child accounts having a username of the DDI, I.e. _tel.6412312312

Inversely, calls to 6412312312 will use the parents location information in the case the child has none.

In CDR, the account will be the child account: _tel.6412312312