XC5-XS User Guide

Overview

  • Generally, day to day configuration will be automated and simplified using 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
  • XC5 XS Nodes create _node.<nodename> accounts to enable authorization/trust between nodes

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

Reserved/Common Account names/prefixes

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

Name/Prefix Type Description
_auth.blacklist full Used to block authentication/calls. Addresses listed in the _auth.blacklist AccountResource:endpoint_ip_address table will be blocked
_carrier. prefixUsed as a prefix for carrier endpoints. These are typically administered by hand, rather than automated
_cos.prefixUsed as a prefix to specify a class of service routing table. Works the same as other routing tables. I.e. _route.default
_node. prefix Used as a prefix by XS nodes to establish trust, fabricate registrations,detect availability of local xs nodes. These entries are automatically generated on restart. They should not be changed or removed
_promptsfullUsed as a single destination to hold mappings of numbers to prompt services. Replaces XC5 servicemap for * codes
_route.default fullIf no default resolver is specified, _route.default is used to provide a default routing table
_route.null full Used as a default resolver to indicate that no further routing should be performed. Avoids _route.default. Use this for accounts/carriers that have access to local accounts only
_tela. prefix Indicates that an e164 number follows the prefix. Used to create a tbnca / a whitelisted subscriber by phone number. Removes the need to add an account number (a:) for singular instances
_tel. prefix Indicates than an e164 number follows the prefix. Used to create a+b whitelisted subscribers by phone number. Removes the need to add an account number for singular instances

Layout

Account features are applied based on the direction of call flow

  • Calls from an endpoint to XC5
AccountResources are considered
Ingress normalization / numbers translated to e.164. "Inward number translation"
Account Numbers used for ingress validation/caller screening
Account Call Rules provide dial plans, resource overloading, router nomination, concurrency limits and other features
Calls are delegated to a target on-net, or a default route resolver for off-net routing
  • Call from XC5 delegating to an Account (heading offnet)
AccountResources are considered
Account Routes provide diversion, resource overloading, media services, concurrency limits and other features
Location services (AccountReg or static endpoint addresses) are used to determine endpoint's position
e.164 to customer facing number translation "Outward number translation"

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 valueDescription
    asserted The caller 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: Mostly the use of an accountnumber is symmetric. The accountnumber is used for both "caller screening" and "called party location". A number may be added with the a: prefix to allow the number to be used only for caller screening
    invalid_pan:1234If 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:12345Regardless 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.

    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: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
FieldValueDescription
New Destination Leave empty. We are not going to change the dialed number
Pack Modifierspin_bypass(1)Indicate that we should bypass the PIN when this rule applies
Required B Number Leave empty. We do not care about the specific dialed number
Priority0The order in which the rule will be applicable. NOTE: Lower numbers are processed first, and only the first applicable rule is used
HitWeight1The ordinal value used to accumulate the internal hitcounter
Required PackTBN(!64%)Indicates this rule will only apply if the Translated B Number does not start with 64)

Applying privacy for a single DDI

  • Create a callrule
FieldValueDescription
New destination Leave empty. An empty destination will allow the call to proceed to the dialed number
Pack Modifiersprivacy(1)Specify that privacy must be set
Required B Number Leave empty. This rule applies to all b numbers
Required Destination Location<Ignore>This rule applies for all destination locations
Priority9The order in which the rule will be applicable. NOTE: Lower numbers are processed first, and only the first applicable rule is used
HitWeight1The ordinal value used to accumulate the internal hitcounter
Required PackTAN(6499201453)The ddi that this rule applies to

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
FieldValueDescription
New destination Leave empty. An empty destination will allow the call to proceed to the dialed number
Pack Modifiersb_blacklist_disable(1)force_pin(1)Specify to disable destination blacklist, and force pin
Required B Number Leave empty. This rule applies to all b numbers
Required Destination Location<Destination Blacklist>This rule applies for only calls the <Destination Blacklist>
Priority9The order in which the rule will be applicable. NOTE: Lower numbers are processed first, and only the first applicable rule is used
HitWeight1The ordinal value used to accumulate the internal hitcounter
Required Pack Leave empty

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 to us, leave the password empty
  • AccountResource: endpoint_ip_address=1.1.x.x
specifies the carriers ip_address for inbound and outgoing routing
for multiple source addresses (inbound only) ipaddress can end with a postfix, ie, endpoint_ip_address=1.1.1.1:in
for multiple destination addresses, equal (time-load-shared) addresses or DNS entries may be specified using +, and second choices can be separated using ,. I.e. 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.
For infrastructure accounts, OPTION probes will be sent by default. send_option_probe can be turned on or off in the accountresource
If using OPTION probes, each XS node (Or if xs_node_group is specified, only those nodes which share the same nodegroup) will resolve DNS names and build Fabricated registrations IF the far end responds.
If OPTION probes are disabled, the Endpoint_resolver will resolve DNS names in the endpoint_ip_address and build account reg entries for those resolved addresses
For static endpoints, 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.
If an endpoint responds to an OPTIONS probe, yet you do not want a specific node to route calls - then create a blackhole route to the destination - effectively disabling the OPTIONS for that node
'Blackhole route in windows
route add X.X.X.X mask Y.Y.Y.Y Z.Z.Z.Z if 1 -p
Where X.X.X.X and Y.Y.Y.Y is the IP range and subnet mask you wish to Null route and Z.Z.Z.Z is the default gateway of your network card.
  • 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 valueDescription
    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 valueDescription
    trustedFor 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 valueDescription
    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:1234If 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:12345Regardless 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 valueDescription
    defaultCalls to the user will use codecs offered by the caller
    force:alaw,mulawThe force prefix forces the following codec list on calls to the user. Native codecs are alaw,mulaw,g729,iLBC
    expand:g729Expanding will add the codec list to the codecs offered by the caller
  • AccountResource:concurrent_call_limit : Specifies the name of the concurrency group. ( cac limit )
The default(2) will need to be increased for carrier interconnects
Members of the same concurrency group will be subjected to their concurrent_call_limit (per xs server).
If no concurrency group is specified in either the local account or the inherited template account, the local account username will be used.
  • 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.
  • 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.
  • SituationOutcome
    destination exists as an AccountNumber (Belongs to an account) The Account/User is contactable directly
    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

  • Routing is performed using an account with an AccountRoute table
  • 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_DATEThe current date/time. Can be used to conditionally apply time of day. CALL_DATE($time: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 networkdrop:404:UnallocatedNZ-NAD-Carrier-LocalNetworknameLMNP(0)
    Calls that have been LMNP ported to local Carrierdrop: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%)
  • $time:<field>(<spec>) Can be used to match TimeDefinitions and regular weekday/time ranges
ExampleDescription
$time:CALL_DATE(!nz_holidays)Matches if NOT a nz_holiday as defined in the TimeDefinitionGroup
$time:CALL_DATE(Mon 08:00-17:00)Matches if CALL_DATE is a Monday between hours of 8am and 5pm)
$time:CALL_DATE(Mon-Tue *,Fri 10:00-11:00)Matches if CALL_DATE is a Monday, a Tuesday, OR if the CALL_DATE is between 10 and 11 on a Friday)
  • Active call count matching - Applies to calls latched to same slave database. Ensure Accounts register to XS nodes sharing the same slave database.
$cac_user(2), matches if the cac_user count is 2 or more
$cac_userChecks to and from Account
$cac_numberChecks calls from Caller and to Called - bothway
$cac_parentChecks to and From Account's Parent - bothway
$cac_f_userChecks calls made from Account
$cac_f_numberCheck calls made from Caller
$cac_f_parentChecks calls made from by Account's Parent
$cac_t_userChecks calls made to Account
$cac_t_numberCheck calls made to Called
$cac_t_parentChecks calls made to by Account's Parent

Pack Modifiers

  • Allow introducing or replacing pack values
ExampleDescription
TAN(1234)force_pin(1)Will replace the Translated A Number, and set the force_pin flag
TAN($reg:^(6419....)(.*)=impersonate($1)TAN($2)) the $reg: prefix applies a regular expression to the TAN. If the TAN matches the expression, further pack values are created/modified from the captures.

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.

Pack ModifierDescription
default_resolver(_route.abc)Changes the default resolver
a_blacklist_disable By default, any calls from caller within the <Caller Blacklist> locationname will be subjected to drop:404:Caller Blacklist. To disable the Caller blacklist, set a_blacklist_disable(1)
b_blacklist_disable By default, any calls to destination locations within the <Destination Blacklist> locationname will be subjected to drop:404:Destination Blacklist. To disable the destination blacklist, set b_blacklist_disable(1)
pin_bypass(1)Turns off pin
pin_force(1)Forces the accounts PIN for this rule. pin_force(2345) will force 2345 as the pin
pin_divert(1)Forces PIN for somebody following our divert
pin_location(<Expensive Destinations>) If a PIN is set, will only ask for a PIN if the call is to a destination with the specified location I.e. <Expensive Destinations>
callrule_continue(1)Where a destination is set, call rules will continue to be applied
impersonate(${TDN})Route as if ${TDN} is making a call
maxtalkMaximum call length seconds
prompt(c:\xyz.slin)Play the file xyz
concurrent_call_limitMax number of calls
TAN(1234)Rewrites the translated a-number (calling party number) to 1234
TDN(1234)Rewrites the translated d-number (diverting number) to 1234

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

PackModifierDescription
digit_mapAllows IVR
route_criteriaForwards data to the next hop. I.e.: XS:regonly avoids any features on the target
route_data User data persisted over multiple route attempts. Can be read/set in RequiredPack/PackModifiers of subsequent routes. Use to implement complex load sharing

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

Mapping ValuesDescription
admin:This is an administrative IVR allowing the PIN holder/account to login and record the ivr prompt for each menu level
#nThis will set menu(n) and rerun Accountroutes from the beginning, allowing a digit_map to jump to a new menu
nnnnnnnnThis will change the new target destination to nnnnnnnn and make a call attempt
drop:nnnThis will drop the call with code nnnn. If the call has been answered, a BYE will be sent with a SIP Reason Header

Example digit_map usage in AccountRoutes

DestinationPriorityPack ModifiersRequiredPackDescription
 0digit_map(1=drop:404,2=6499201453,3=#2,4=admin)menu(1)As menu(1) is the default, this digit_map will be applied when this account is called. Pressing 3 jumps to menu 2
  1 digit_map(1=64123123123,2..=6412123..,3=#1,4T=) menu(2) This menu will only apply when option 3 is pressed during menu(1). If 2 is pressed, a further 2 digits will be collected then appended to 6412123 and a call attempt will be made. Pressing 3 will return to menu #1

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 (withfall-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) 

Star Codes / Smart Codes

  • 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

**XXPlace call using Speed Dial 100
*22Auto attendant service main prompt setup
*23Auto attendant service playback main recording
*24Auto attendant service enable
*25Auto attendant service disable
*26Auto attendant options configuration
*28Park call / Hold Music
*30Enable Block caller ID (persistent)
*31Disabled Block caller ID (persistent)
*33XBarge-In (requires secure pin)
*44Call recording enable
*45Call recording disable
*46XPlace a call with recording enabled
*60Blacklist the last caller
*65XPer call Allow Caller ID
*66Last number redial
*67XPer call Block Caller ID
*69Call Return
*72Call forward unconditional (always) Enable
*72XCall forward unconditional (always) with number provided Enable
*73Call forward unconditional (always) Disable
*75XXSpeed Dial 100 Setup
*77Enable anonymous caller rejection
*78Do not disturb Enable
*79Do not disturb Disable
*87Disable anonymous caller rejection
*90Call forward busy Enable
*90XCall forward busy with number provided Enable
*91Call forward busy (always) Disable
*92Call forward noanswer Enable
*92XCall forward noanswer with number provided Enable
*93Call forward noanswer Disable
*94Call forward unreachable Enable
*94XCall forward unreachable with number provided Enable
*95Call forward unreachable Disable
*97XCall Pickup
*98Group Pickup

Fraud

  • The fraud mechanism applies for connected calls to locations specified in the <Expensive Destinations> location.
  • The accountpack can override the default fraud configuration: consume(180)limit(900)
  • The counters are maintained in limit.expensive within either the AccountANI or the Account Pack (If account ani does not match)
  • When the threshold has triggered, a callrule is added to either the ANI or the entire account (Whichever is first possible). The call rule sets the b number to 640000 and changes the default_resolver to _route.fraudblock
  • The _route.fraudblock account is created if it does not already exist.
  • All onnet calls will still be able to proceed

  • *_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 or ANI, delete the appropriate call rule
  • If you need to disable the fraud mechanism completely, you can set the account pack: fraud_check(0)

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

Plugin DestinationDescription
admin:Allows recording of customer prompts and greetings for ivr/attendant/email functions. Requires IVR login.
admin_divert: Allows specifying new diversion destination in AccountRoute with routeOrder 99999. The new diversion destination will be subjected to number translation using pack values noa(unk)module(ivr). Requires IVR login.
drop:code Will drop the call with the specified code. (I.e. drop:404). If the call is already answered, a Reason header will be included with the code
drop:code:descriptionWill drop the call with the specified code, and also include the description in the CDR and SIP response
drop:code:description:promptAs per above and will also play the prompt from the local machines prompts directory
pickup_group:groupname Will allow this call to pickup a ringing call which has AccountResource:pickup_group=groupname. Note: groupnames are system wide. Groupnames should be named uniquely for each pickup group
email:123@456.comCustomer prompt, record and forward to email. Requires email relay setup
fax2email:123@456.comReceives fax and forwards to email. Requires email relay setup

  • 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

PriorityTranslation TypeRequired NumberNew NumberRequiredPackDescription
1Inward B Translation006161%noa(unk)module(ivr)Allow AUS
2Inward B Translation00drop:404noa(unk)module(ivr)Block 00 prefixed numbers
3Inward B Translation064%noz(unk)module(ivr)Translation for Local NZ numbers

Number translation

The XC5 system requires and stores all internal numbers natively as INT/e.164. Therefore 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.

A Nature of address (noa) tag is conditionally applied to calls

  • Ingress calls have no noa specified. 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
    PriorityOnly 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
    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 PackIf specified, this translation will only apply if this call contains values specified in the required pack

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

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 accessability : Nodes must ignore node_group when probing each other
  • Applied to account:
Restricts probes to the node group
Identifies/Locates which nodes know about the accounts registration/cac limits etc. (Hence the node_group/db relationship)

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
  • Attribute bill to local_user
  • Rate on calling and called party numbers
  • Consider caller_user for reconciliation of ingress charges
  • consider called_user for reconciliation of egress charges

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