Block lists can either be whitelists or blacklists and are controlled by the User Preferences block_in_mode, block_out_mode and their administrative counterparts.

You can change a list mode from one to the other at any time.

The list contents are controlled by the User Preferences block_in_list, block_out_list and their administrative counterparts. Click on the Edit button in the Preferences view to define the list entries.

In block list entries, you can provide shell patterns like * and []. The behavior of the list is controlled by the block_xxx_mode feature (so they are either allowed or rejected). In our example above we have block_out_mode set to blacklist, so all calls to US numbers and to the Austrian number +431234567 are going to be rejected.

Click the Close icon once you’re done editing your list.

For incoming call, the User Preference block_in_clir and adm_block_in_clir controls whether or not to reject incoming calls with number suppression (either "[Aa]nonymous" in the display- or user-part of the From-URI or a header Privacy: id is set). This flag is independent from the Block Mode.

To create an NCOS Level, go to Settings→NCOS Levels and press the Create NCOS Level button.

Select a reseller, enter a name, select the mode and add a description, then click the Save button.

To define the rules within the newly created NCOS Level, click on the Patterns button of the level.

There are 2 groups of patterns where you can define matching rules for the selected NCOS Level:

Figure 27. NCOS Patterns List

In the NCOS Number Patterns view you can create multiple patterns to define your level, one after the other. Click on the Create Pattern Entry Button on top and fill out the form.

Figure 28. Create NCOS Number Pattern

In this example, we block (since the mode of the level is blacklist) all numbers starting with 439. Click the Save button to save the entry in the level.

There are 2 options that help you to easily define specific number ranges that will be allowed or blocked, depending on whitelist / blacklist mode:

In the NCOS LNP Carriers view you can select specific LNP Carriers — i.e. carriers that host the called ported numbers — that will be allowed or blocked for routing calls to them (whitelist / blacklist mode, respectively).

An example of NCOS LNP Carrier definition:

Figure 29. Create NCOS LNP Carrier

In the above example we created a rule that blocks calls to "LNP_Carr1" carrier, supposing we use blacklist mode of the NCOS Level.

In the LNP NCOS Number Patterns view you can create multiple patterns to restrict NCOS LNP Carrier matching, one after the other. Click on the Create LNP Pattern Entry Button on top and fill out the form.

Figure 30. Create NCOS LNP Carrier Pattern

Considering the example before and adding the pattern shown in the picture, the rule now blocks only calls to "LNP_Carr1" carrier that starts with 390.

The below table gives an overview of all the possible combinations of NCOS and NCOS LNP Carrier:

The parameter kamailio.proxy.lnp.strictly_check_ncos contained in /etc/ngcp-config/config.yml specify whether the NCOS LNP should be evaluated even if the LNP lookup was not previously executed (because not required by the inbound/outbound call) or if it didn’t return any occurrence. If set to yes, a whitelist NCOS will fail if the LNP lookup doesn’t return any match. The parameter has no impact on blacklist NCOS.

Once you’ve defined your NCOS Levels, you can assign them to local subscribers. To do so, navigate to Settings→Subscribers, search for the subscriber you want to edit, press the Details button and go to the Preferences View. There, press the Edit button on either the ncos or adm_ncos setting in the Call Blockings section.

You can assign the NCOS level to all subscribers within a particular domain. To do so, navigate to Settings→Domains, select the domain you want to edit and click Preferences. There, press the Edit button on either ncos or admin_ncos in the Call Blockings section.

Note: if both domain and subscriber have same NCOS preference set (either ncos or adm_ncos, or both) the subscriber’s preference is used. This is done so that you can override the domain-global setting on the subscriber level.

In some countries there are regulatory requirements that prohibit subscribers from forwarding their numbers to special numbers like emergency, police etc. While Sipwise C5 does not deny provisioning Call Forward to these numbers, the administrator can prevent the incoming calls from being actually forwarded to numbers defined in the NCOS list: select the appropriate NCOS level in the domain’s or subscriber’s preference adm_cf_ncos. This NCOS will apply only to the Call Forward from the subscribers and not to the normal outgoing calls from them.

Click on Manage Destination Sets to see a list of available sets. The quickset_cfu has been implicitly created during our creation of a simple call forward. You can edit it to add more destinations, or you can create a new destination set.

When you close the Destination Set Overview, you can now assign your new set in addition or instead of the quickset_cfu set.

Press Save to store your settings.

Click on Manage Time Sets in the advanced call-forward menu to see a list of available time sets. By default there are none, so you have to create one.

You need to provide a Name, and a list of Periods where this set is active. If you only set the top setting of a date field (like the Year setting in our example above), then it’s valid for only this setting (like the full year of 2013 in our case). If you provide the bottom setting as well, it defines a period (like our Month setting, which means from beginning of April to end of September). For example, if a CF is set with the following timeset: "hour { 10-12 } minute { 20-30 }", the CF will be matched within the following time ranges:

If you close the Time Sets management, you can assign your new time set to the call forwards you’re configuring.

Once the Advanced View of the call forward definition has been opened, you will need to press the Manage Source Sets button to start defining new Source Sets or managing an existing one. The following image shows the Source Set definition dialog:

Figure 31. Creating a Call Forward Source Set

You will need to fill in the Name field first, the Mode: whitelist or blacklist, the is_regex flag and finally in the Source field you can enter:

You can add more patterns to the Source Set by pressing the Add another source button. When you finished adding all patterns, press the Save button. You will then see the below depicted list of Source Sets:

Figure 32. List of Call Forward Source Sets

Once the Advanced View of the call forward definition has been opened, you will need to press the Manage B-Number Sets button to start defining new B-Number Sets or managing an existing one. The following image shows the B-Number Set definition dialog:

Figure 33. Creating a Call Forward B-Number Set

You will need to fill in the Name field first, the Mode: whitelist or blacklist, the is_regex flag and finally in the B-Number field you can enter:

You can add more patterns to the B-Number Set by pressing the Add another B-Number button. When you finished adding all patterns, press the Save button. You will then see the below depicted list of B-Number Sets:

Figure 34. List of Call Forward B-Number Sets

As additional step you can define a Destination Set as described in Destination Sets subchapter. For our example, we have defined the following Destination Set:

Figure 35. List of Call Forward Destination Sets

A final step of defining the call forward settings is selecting a Destination, a Time Set, a Source Set and a B-Number Set, as shown in the image below. Please note that there is no specific Time Set selected in our example, that means the call forward rule is valid (as shown) <always>.

Figure 36. Definition of a Call Forward with Source and Destination Sets

Once all the settings have been defined and the changes are saved, you will see the call forward entry (in our example: Call Forward Unconditional), with the names of the selected Destination, Time Set, Source Sets and B-Number Set provided, at SubscriberPreferences → Call Forwards location on the web interface:

Figure 37. List of Call Forward with Source and Destination Sets

LNP Carriers are defined by an arbitrary Name for proper identification (e.g. British Telecom) and contain a Prefix which can be used as routing prefix in LNP Rewrite Rules and subsequently in Peering Rules to route calls to the proper carriers. The LNP prefix is written to CDRs to identify the selected carrier for post processing and analytics purposes of CDRs. LNP Carrier entries also have an Authoritative flag indicating that the numbers in this block belong to the carrier operating Sipwise C5 . This is useful to define your own number blocks, and in case of calls to those numbers reject the calls if the numbers are not assigned to local subscribers (otherwise they would be routed to a peer, which might cause call loops). Finally the Skip Rewrite flag skips executing of LNP Rewrite Rules if no number manipulation is desired for an LNP carrier.

LNP Carriers contain one or more LNP Numbers. Those LNP Numbers are defined by a Number entry in E164 format (<cc><ac><sn>) used to match a number against the LNP database. Number matching is performed on a longest match, so you can define number blocks without specifying the full subscriber number (e.g. a called party number 431999123 is going to match an entry 431999 in the LNP Numbers).

For an LNP Numbers entry, an optional Routing Number can be defined. This is useful to translate e.g. premium 900 or toll-free 800 numbers to actual routing numbers. If a Routing Number is defined, the called party number is implicitly replaced by the Routing Number and the call processing is continued with the latter. For external billing purposes, the optional Type tag of a matched LNP number is recorded in CDRs.

An optional Start Date and End Date makes it possible to schedule porting work-flows up-front by populating the LNP database with certain dates, and the entries are only going to become active with those dates. Empty values for start indicate a start date in the past, while empty values for end indicate an end time in the future during processing of a call, allowing to define infinite date ranges. As intervals can overlap, the LNP number record with a start time closest to the current time is selected.

In order to activate Local LNP during routing, the feature must be activated in config.yml. Set kamailio→proxy→lnp→enable to yes and kamailio→proxy→lnp→type to local.

When a call arrives at the system, the calling and called party numbers are first normalized using the Inbound Rewrite Rules for Caller and Inbound Rewrite Rules for Callee within the rewrite rule set assigned to the calling party (a local subscriber or a peer).

If the called party number is not assigned to a local subscriber, or if the called party is a local subscriber and has the subscriber/domain preference lnp_for_local_sub set, the LNP lookup logic is engaged, otherwise the call proceeds without LNP lookup. The further steps assume that LNP is engaged.

If the call originated from a peer, and the peer preference caller_lnp_lookup is set for this peer, then an LNP lookup is performed using the normalized calling party number. The purpose for that is to find the LNP prefix of the calling peer, which is then stored as source_lnp_prefix in the CDR, together with the selected LNP number’s type tag (source_lnp_type). If the LNP lookup does not return a result (e.g. the calling party number is not populated in the local LNP database), but the peer preference default_lnp_prefix is set for the originating peer, then the value of this preference is stored in source_lnp_prefix of the CDR.

Next, an LNP lookup is performed using the normalized called party number. If no number is found (using a longest match), no further manipulation is performed.

If an LNP number entry is found, and the Routing Number is set, the called party number is replaced by the routing number. Also, if the Authoritative flag is set in the corresponding LNP Carrier, and the called party number is not assigned to a local subscriber, the call is rejected. This ensures that numbers allocated to the system but not assigned to subscribers are dropped instead of routed to a peer.

Next, if the LNP carrier does not have the Skip Rewriting option set, the LNP Rewrite Rules for Callee are engaged. The rewrite rule set used is the one assigned to the originating peer or subscriber/domain via the rewrite_rule_set preference. The variables available in the match and replace part are, beside the standard variables for rewrite rules:

Typically, you would create a rewrite rule to prefix the called party number with the callee_lnp_prefix by matching ^([0-9]+)$ and replacing it by ${callee_lnp_prefix}\1.

Once the LNP processing is completed, the system checks for further preferences to finalize the number manipulation. If the originating local subscriber or peer has the preference lnp_add_npdi set, the Request URI user-part is suffixed with ;npdi. Next, if the preference lnp_to_rn is set, the Request URI user-part is suffixed with ;rn=LNP_ROUTING_NUMBER, where LNP_ROUTING_NUMBER is the Routing Number stored for the number entry in the LNP database, and the originally called number is kept in place. For example, if lnp_to_rn is set and the number 1800123 is called, and this number has a routing number 1555123 in the LNP database, the resulting Request-URI is sip:1800123;rn=1555123@example.org.

Finally, the destination_lnp_prefix in the CDR table is populated either by the prefix defined in the Carrier of the LNP database if a match was found, or by the default_lnp_prefix preference of the destination peer or subscriber/domain.

The Sipwise C5 provides means to allow or block calls towards ported numbers that are hosted by particular LNP carriers. Please visit Section 7.3.2.2, “Creating Rules per NCOS Level” in the handbook to learn how this can be achieved.

If a call originated from a peer and the peer preference force_outbound_calls_to_peer is set to force_nonlocal_lnp (the if callee is not local and is ported selection in the panel), the call is routed back to a peer selected via the peering rules.

This ensures that if a number once belonged to your system and is ported out, but other carriers are still sending calls to you (e.g. selecting you as an anchor network), the affected calls can be routed to the carrier the number got ported to.

The LNP database can be exported to CSV, and in the same format imported back to the system. On import, you can decide whether to drop existing data prior to applying the data from the CSV.

The CSV file format contains the fields in the following order:

If a match in the local LNP table is found corresponding LNP Carrier code will be stored in CDR data.

Additionally two dedicated headers can be added to the outgoing SIP message:

This feature is not enabled by default, but can be activated with the following parameters:

There is a special case when the dialed number is recognized as an emergency number, but the emergency number is not available for the geographic area the calling party is located in.

In such a case the emergency mapping lookup will return an emergency prefix, but the value of this will be NULL. Therefore the call is rejected and an announcement is played. The announcement is a newly defined sound file referred as emergency_geo_unavailable.

It is possible to configure the rejection code and reason in /etc/ngcp-config/config.yml file, the parameters are: kamailio.proxy.early_rejects.emergency_invalid.announce_code and kamailio.proxy.early_rejects.emergency_invalid.announce_reason.

The Sipwise C5 offers the possibility to upload / download emergency mapping entries in form of CSV files. This operation is available for each reseller, and is very useful if a reseller has many mapping entries.

Downloading Emergency Mapping List

One has to navigate to Settings → Emergency Mapping menu and then press the Download CSV button to get the list of mapping entries in a CSV file. First the reseller must be selected, then the Download button must be pressed. As an example, the entries shown in "Emergency Mapping List" picture above would be written in the file like here below:

EmergCont_1,133,E1_133_
EmergCont_1,144,E1_144_
EmergCont_2,133,E2_133_

The CSV file has a plain text format, each line representing a mapping entry, and contains the following fields:

Uploading Emergency Mapping List

Uploading a CSV file with emergency mapping entries may be started after pressing the Upload CSV button. The following data must be provided:

Figure 43. Uploading Emergency Mapping Data

The CSV file for the upload has the same format as the one used for download.

Sipwise C5 can enhance pbx integration providing three different extended dialing modes:

Extended dialing modes are editable under Number Manipulations→extended_dialing_mode.

Fallback procedure is on by default and usually applies to extended matching or e164_to_ruri modes. If the callee UAC replies with a 404 not found error, the fallback feature triggers the generation of a new INVITE. In this case the new Request URI will be set accordingly to the extended_dialing_mode and e164_to_ruri values.

The whole 404 fallback procedure can however be disabled activating the no_404_fallback option under subscriber’s or domain’s preferences.

The SIP PBX by default inherits the domain dialplan which usually has rewrite rules applied to normal Class 5 subscribers with inbound rewrite rules normalizing the dialed number to the E.164 standard. If most users of this domain are Class 5 subscribers the dialplan may supply calling number in national format - see Section 6.7, “Configuring Rewrite Rule Sets”. While the SIP-PBX trunk configuration can be sometimes amended it is a good idea in sense of SIPconnect recommendation to send only the global E.164 numbers.

Moreover, in mixed environments with Sipwise C5 Cloud PBX sharing the same domain with SIP trunking (SIP-PBX) customers the subscribers may have different rewrite rules sets assigned to them. The difference is caused by the fact that the dialplan for Cloud PBX is fundamentally different from the dialplan for SIP trunks due to extension dialing, where the Cloud PBX subscribers use the break-out code to dial numbers outside of this PBX.

The SIPconnect compliant numbering plan can be accommodated by assigning Rewrite Rules Set to the SIP-PBX subscriber. Below is a sample Rewrite Rule Set for using the global E.164 numbers with plus required for the calling and called number format compliant to the recommendation.

Assign the aforementioned Rewrite Rule Set to the SIP-PBX subscribers.

The following configuration is needed for your platform to populate the From and To headers and Request-URI of the INVITE request with "user=phone" parameter as per RFC 3261 Section 19.1.1 (if the user part of the URI contains telephone number formatted as a telephone-subscriber).

The following is our common configuration that covers the calling number presentation in a variety of use-cases, including the incoming calls, on-net calls and Call Forward by the platform:

The above parameters can be tuned to operator specifics as required. You can override these settings in the Subscriber Preferences if particular subscribers need special settings.

Externally forwarded call. If the call forward takes place inside the SIP-PBX it can use one of the following specification for signaling the diversion number to the platform:

If a SIP-PBX cannot perform the digest authentication, you can authenticate it by its source IP address in Sipwise C5. To configure the IP-based authentication, go to the subscriber’s preferences (Details→ Preferences→Trusted Sources) and specify the IP address of the SIP-PBX in the Source IP field.

To authenticate multiple subscribers from the same IP address, use theFrom field to distinguish these subscribers.

When this feature is configured for a subscriber, Sipwise C5 authenticates all calls that arrive from the specified IP address without challenging them.

The parameters of peer probing are found in the main system configuration file /etc/ngcp-config/config.yml. You can see the complete list of configuration parameters in Section 1.13, “kamailio” of the handbook, while the most significant ones are discussed here.

Enabling peer probing system-wide happens through the kamailio.proxy.peer_probe.enable parameter. If it is set to yes (which is the default value) then Sipwise C5 will consider probing of individual peering servers based on their settings.

Timeout of a single probing request can be defined through kamailio.proxy.peer_probe.timeout parameter. This is a value interpreted as seconds while Sipwise C5 will wait for a SIP response from the peering server. Default is 5 seconds.

The probing interval can be set through the kamailio.proxy.peer_probe.interval parameter. This is the time period in seconds that determines how often a probing request is sent to the peering servers. Default is 10 seconds.

The SIP method used for probing requests can be defined through kamailio.proxy.peer_probe.method parameter. Allowed values are: OPTIONS (default) and INFO.

If no available peering server is found, the call is rejected with the response code and reason configured in kamailio.proxy.early_rejects.peering_unavailable.announce_code and kamailio.proxy.early_rejects.peering_unavailable.announce_reason. If a sound file is configured within the system sound set assigned to the calling party, an announcement is played as early media before the rejection.

When the peer probing feature is enabled on system-level, it is possible to add each individual peering server to the list of probed endpoints. You can change the probed status of a server in two ways:

Enable probing of a peering server via the admin web interface

Figure 52. Enable Probing of Peering Server

Enable probing of a peering server via the REST API

In all cases you have to set the probe property to true in order to enable probing, and to false in order to disable probing. Default value is false and this property may be omitted in a create/update request, which ensures backward compatibility of the /api/peeringservers API resource.

Each kamailio-proxy instance on the proxy nodes performs the probing individually for performance reasons. Each proxy holds its result in its cache to avoid central storage and replication of the probing results.

Each peering server is cross-checked against the hash table filled during outbound probing requests and is skipped by call routing logic, if a match is found.

On start or restart of the kamailio-proxy instance, the probing will start after the first interval, and NOT immediately after start. In the first probing interval the proxy will always try to send call traffic to peering servers until the first probing round is finished, and will only then start to skip unavailable peering servers.

A new configuration template: /etc/ngcp/config/templates/etc/kamailio/proxy/probe.cfg.tt2 is introduced to handle outbound probing requests.

A new DB column: provisioning.voip_peer_hosts.probe with type TINYINT(1) (boolean) is added to the DB schema.

A peer status change will populate the kamailio.dispatcher table, inserting the SIP URI in format sip:$ip:$port;transport=$transport in dispatcher group 100, which defines the probing group for peering servers.

Also the kamailio.dispatcher.attrs column is populated with a parameter peerid=$id. This ID is used during probing to load the peer preferences: outbound_socket and lbrtp_set, that are required to properly route the probing request.

Since access might need to be provided from external networks like PSTN/Mobile, and since certain SIP phones do not support calling alphanumeric numbers to dial voicebox, you can map any number to the voicebox URIs using rewrite rules.

To do so, you can provision a match pattern e.g. ^(00|\+)12345$ with a replace pattern voicebox, voiceboxpass or voiceboxpin to map a number to either password-less for the first one or password-based IVR access for the other two. Create a new rewrite rule with the Inbound direction and the Callee field in the corresponding rewrite rule set.

For inbound calls from external networks, assign this rewrite rule set to the corresponding incoming peer. If you also need to map numbers for on-net calls, assign the rewrite rule set to subscribers or the whole SIP domain.

When reaching voiceboxpass, the subscriber is prompted for her mailbox number and a password. All numbers assigned to a subscriber are valid input (primary number and any alias number). By default, the required format is in E.164, so the subscriber needs to enter the full number including country code, for example 4912345 if she got assigned a German number.

While reaching for voiceboxpin, the subscriber is only prompted for the PIN.

You can globally configure a rewrite rule in config.yml using asterisk.voicemail.normalize_match and asterisk.voicemail.normalize_replace, allowing you to customize the format a subscriber can enter, e.g. having ^0([1-9][0-9]+)$ as match part and 49$1 as replace part to accept German national format.

The standard voice mail greeting is the "unavailable" greeting. This is used if you don’t answer the phone and so the call is directed to your voice mailbox.

If you wish, you can record a custom greeting used when someone calls you and you are currently on the phone. This is called your "Busy" greeting.

You can also record a temporary greeting. If it exists, a temporary greeting will always be played instead of your "busy" or "unavailable" greetings. This could be used, for example, if you are going on vacation or will be out of the office for a while and want to inform people not to expect a return call anytime soon. Using a temporary greeting avoids having to change your normal unavailable greeting when you leave and when you come back.

When a caller leaves a message for you,the system will put the message into the "New Messages" folder. If you listen to the message, but do not delete the message or save the message to a different folder, it will automatically move the message to the "Old Messages" folder. When you first log into your mailbox, the Voicemail System will make the "New Messages" folder the current folder if you have any new messages. If you do not have any new messages the it will make the "Old Messages" folder the current folder.

The prerequisite for generating a new invoice is that the customer has to have an invoice template assigned to him.

The following example shows a CURL command that will request generation of an invoice:

curl -i -X POST -H 'Connection: close' -H 'Content-Type: application/json' \
  --user adminuser:adminpwd -k 'https://127.0.0.1:1443/api/invoices/'      \
  --data-binary '{ "customer_id" : "79", "template_id" : "1",              \
  "period_start": "2017-11-01 00:00:00", "period_end": "2017-11-30 23:59:59"  }'

Please note that in this operation we used the /api/invoices path (the invoices collection) and a POST request on it to create a new invoice item.

In case of a successful operation, Sipwise C5 will reply with 201 Created HTTP status and send the ID of the invoice in Location header. In our example the new invoice item may be directly referred as /api/invoices/3 (ID = 3).

HTTP/1.1 201 Created
Server: nginx
Date: Tue, 14 Nov 2017 13:38:40 GMT
Content-Length: 0
Connection: close
Location: /api/invoices/3
Set-Cookie: ngcp_panel_session=d5e4a8dd003fd7cac646653a6b5aefa703cf3e66; path=/; expires=Tue, 14-Nov-2017 14:38:38 GMT; HttpOnly
X-Catalyst: 5.90114
Strict-Transport-Security: max-age=15768000

In case of a failed operation, e.g. when we request an invoicing period that is invalid for the customer, Sipwise C5 will reply with 422 Unprocessable Entity or 500 Internal Server Error HTTP status.

You can download properties / data of a specific invoice by selecting the item by its ID, using an HTTP GET request.

curl -i -X GET -H 'Connection: close' --user adminuser:adminpwd -k \
'https://127.0.0.1:1443/api/invoices/3'

The above request will return a JSON data structure containing invoice properties:

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 15 Nov 2017 12:13:04 GMT
Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/"; charset=utf-8
Content-Length: 759
Connection: close
Link: </api/invoices/>; rel=collection
Link: <http://purl.org/sipwise/ngcp-api/>; rel=profile
Link: </api/invoices/3>; rel="item self"
Link: </api/invoices/3>; rel="item http://purl.org/sipwise/ngcp-api/#rel-invoices"
Link: </api/customers/79>; rel="item http://purl.org/sipwise/ngcp-api/#rel-customers"
Set-Cookie: ngcp_panel_session=219feccbee4fa936defd1ee511c84efe7b5a6d6a; path=/; expires=Wed, 15-Nov-2017 13:13:03 GMT; HttpOnly
Strict-Transport-Security: max-age=15768000

{
   "_links" : {
      "collection" : {
         "href" : "/api/invoices/"
      },
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "ngcp:customers" : {
         "href" : "/api/customers/79"
      },
      "ngcp:invoices" : {
         "href" : "/api/invoices/3"
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp-api/"
      },
      "self" : {
         "href" : "/api/invoices/3"
      }
   },
   "amount_net" : 0,
   "amount_total" : 0,
   "amount_vat" : 0,
   "id" : 3,
   "period_end" : "2017-11-30T23:59:59+00:00",
   "period_start" : "2017-11-01T00:00:00+00:00",
   "sent_date" : null,
   "serial" : "INV2017110000003"
}

It is also possible to query the complete invoices collection and use a filter (e.g. invoicing period, customer ID, etc.) to get the desired invoice item. In the example below we request all available invoices that belong to the customer with ID "79".

curl -i -X GET -H 'Connection: close' --user adminuser:adminpwd -k \
'https://127.0.0.1:1443/api/invoices/?customer_id=79'

The returned dataset is now slightly different because it is represented as an array of items, although in our example the array consist of only 1 item:

{
   "_embedded" : {
      "ngcp:invoices" : [
         {
            "_links" : {
               "collection" : {
                  "href" : "/api/invoices/"
               },
               "curies" : {
                  "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
                  "name" : "ngcp",
                  "templated" : true
               },
               "ngcp:customers" : {
                  "href" : "/api/customers/79"
               },
               "ngcp:invoices" : {
                  "href" : "/api/invoices/3"
               },
               "profile" : {
                  "href" : "http://purl.org/sipwise/ngcp-api/"
               },
               "self" : {
                  "href" : "/api/invoices/3"
               }
            },
            "amount_net" : 0,
            "amount_total" : 0,
            "amount_vat" : 0,
            "id" : 3,
            "period_end" : "2017-11-30T23:59:59+00:00",
            "period_start" : "2017-11-01T00:00:00+00:00",
            "sent_date" : null,
            "serial" : "INV2017110000003"
         }
      ]
   },
   "_links" : {
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "ngcp:invoices" : {
         "href" : "/api/invoices/3"
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp-api/"
      },
      "self" : {
         "href" : "/api/invoices/?page=1&rows=10"
      }
   },
   "total_count" : 1
}

You can download a specific invoice as a PDF file in the following way:

curl -X GET -H 'Connection: close' -H 'Accept: application/pdf' \
  --user adminuser:adminpwd -k 'https://127.0.0.1:1443/api/invoices/3' > result.pdf

Please note that in the example above we do not add the "-i" option that would also include the headers of the HTTP response in the output file. The output of the CURL command, i.e. the PDF file, is saved as "result.pdf" locally.

In order to delete an invoice item you have to send a DELETE request on the specific item:

curl -i -X DELETE -H 'Connection: close' --user adminuser:adminpwd -k \
'https://127.0.0.1:1443/api/invoices/3'

In case of successful deletion Sipwise C5 should send HTTP status 204 No Content as a response:

HTTP/1.1 204 No Content
Server: nginx
Date: Wed, 15 Nov 2017 13:42:42 GMT
Connection: close
Set-Cookie: ngcp_panel_session=10b66a6baf25a09739c2bb2377c70ecceee78387; path=/; expires=Wed, 15-Nov-2017 14:42:42 GMT; HttpOnly
X-Catalyst: 5.90114
Strict-Transport-Security: max-age=15768000

Invoice templates can be searched, created, edited and deleted in the invoice templates management interface.

Invoice template creation is separated on two steps:

To register new invoice template press "Create Invoice Template" button.

On the invoice template meta information form following parameters can be specified:

All form fields are mandatory.

After registering new invoice template you can change invoice template structure in WYSIWYG SVG editor and preview result of the invoice generation based on the template.

Invoice template is a XML SVG source, which describes content, look and position of the text lines, images or other invoice template elements. The Sipwise C5 provides embedded WYSIWYG SVG editor svg-edit 2.6 to customize default template. The Sipwise C5 svg-edit has some changes in layers management, image edit, user interface, but this basic introduction still may be useful.

Template refers to the owner reseller contact ("rescontact"), customer contract ("customer"), customer contact ("custcontact"), billing profile ("billprof"), invoice ("invoice") data as variables in the "[%%]" mark-up with detailed information accessed as field name after point e.g. [%invoice.serial%]. During invoice generation all variables or other special tokens in the "[% %]" mark-ups will be replaced by their database values.

Press on "Show variables" button on invoice template content page to see full list of variables with the fields:

You can add/change/remove embedded variables references directly in main svg-edit window. To edit text line in svg-edit main window double click on the text and place cursor on desired position in the text.

After implementation of the desired template changes, invoice template should be saved.

To return to Sipwise C5 invoice template default content you can press on the "Discard changes" button.

Layers

Default template contains three groups elements (<g/>), which can be thinked of as pages, or in terms of svg-edit - layers. Layers are:

To see all invoice template layers, press on "Layers" vertical sign on right side of the svg-edit interface:

Side panel with layers list will be shown.

One of the layers is active, and its element can be edited in the main svg-edit window. Currently active layer’s name is bold in the layers list. The layers may be visible or invisible. Visible layers have "eye" icon left of their names in the layers list.

To make a layer active, click on its name in the layers list. If the layer was invisible, its elements became visible on activation. Thus you can see mixed elements of some layers, then you can switch off visibility of other layers by click on their "eye" icons. It is good idea to keep visibility of the "Background" layer on, so look of the generated page will be seen.

Edit SVG XML source

Sometimes it may be convenient to edit svg source directly and svg-edit makes it possible to do it. After press on the <svg> icon in the top left corner of the svg-edit interface:

SVG XML source of the invoice template will be shown.

SVG source can be edited in place or copy-pasted as usual text.

To save your changes in the svg xml source, first press "OK" button on the top left corner of the source page:

And then save invoice template changes.

Change logo image

After image uploaded save invoice template changes.

To save invoice template content changes press button "Save SVG".

You will see message about successfully saved template. You can preview your invoice look in PDF format. Press on "Preview as PDF" button.

Invoice preview will be opened in the new window.

Enabling the function requires changing the value of rtpproxy.recording.enable parameter to “yes”. In order to make the new configuration active, it’s necessary to do:

ngcpcfg apply 'Activated call recording'

Description of configuration parameters:

If Call Recording is enabled you can see 2 rtpengine processes running when checking Sipwise C5 system state with ngcp-service tool:

root@sp1:/etc/ngcp-config# ngcp-service summary
Ok Service                        Managed    Started   Status
-- ------------------------------ ---------- --------- ---------
…
   kamailio-lb                    managed    by-ha     active
   ngcp-voisniff                  managed    by-ha     active
   rtpengine                      managed    by-ha     active
   rtpengine-recording            managed    by-ha     active
…

Activating Call Recording for e.g. a Subscriber: please use NGCP’s admin web interface for this purpose. On the web interface one has to navigate as follows: Settings → Subscribers → select subscriber Details → Preferences → NAT and Media Flow Control. Afterwards the record_call option has to be enabled by pressing the Edit button and ticking the checkbox.

Figure 62. Activating Call Recording

It is possible to list existing call recordings of a Subscriber through the admin web interface of NGCP. In order to do so, please navigate to: Settings → Subscribers → select subscriber Details → Call Recordings

Figure 63. Listing Call Recordings

If you select an item in the list, besides the main properties such as the time of call and the SIP Call-ID, you can retrieve the details of the related call (press the Call Details button), get the list of recorded files (press the Recorded Files button) or Delete the recorded call.

When selecting Call Details you will see the most important accounting data of the call. Furthermore you can see the SIP Call Flow or the complete Call Details if you press the respective buttons.

Figure 64. Listing Call Details for a Recording

When navigating to Recorded Files of a call you will be presented with a list of files. For each file item:

Figure 65. Listing Files for a Recording

Packetisation time in milliseconds. Normally Sipwise C5 lets the RTP endpoints select and negotiate the packetisation time they want to use. Setting this option to anything other than unchanged will engage the transcoding engine towards this subscriber or peer even if none of the other transcoding options are set, in which case the media will be repacketised.

For example, setting this to 40 ms would mean that each RTP packet sent towards this subscriber or peer would contain 40 milliseconds worth of audio, even if the other side of the call sends media that is packetised differently. It would also make Sipwise C5 indicate towards this subscriber or peer that it would prefer to receive audio in 40 millisecond packets (through the a=ptime SDP attribute).

Enabling one of these options adds the selected codecs to the list of codecs offered to this subscriber or peer, even if the original list of offered codecs did not include it. If this additional codec ends up being accepted by this subscriber or peer, then it will be transcoding to the first supported codec that was originally offered.

For example, if a calling RTP client A indicates support for PCMA (G.711 a-Law) as well as G.722, and calls a subscriber B that is configured for transcoding to G.729, then subscriber B would be offered PCMA, G.722, and G.729 by Sipwise C5. If subscriber B then accepts G.729 and starts sending G.729, Sipwise C5 would engage its transcoding engine and transcode the audio to PCMA (because PCMA and not G.722 was the codec preferred by A) before forwarding it to A. Vice versa, PCMA arriving from A would be transcoded to G.729 before being sent to B. (If B were to reject G.729 and instead starts to send PCMA or G.722, no transcoding would happen.)

Notes on individual codecs:

Some codecs (Opus and G.723.1 in particular) can be configured for different bitrates, which would impact the amount of network bandwidth they use, as well as the audio quality produced. For Opus, different bitrates can be selected for their mono and stereo instances. Selecting a bitrate has no effect if transcoding to the respective codec is not engaged.

AMR and AMR-WB support dynamic mode switching (adapting the bitrate) during runtime. The configurable bitrate therefore is only the initial bitrate at which the encoder is started, and is further constrained by the mode-set option.

The mode-set is a list of comma-separated AMR modes, e.g. 0,1,2,3. If a mode-set is received from a remote peer, then only the modes (bitrates) given in the list will be used for the encoder. If a specific bitrate is also configured, then this bitrate will be used as the highest possible starting bitrate. If this bitrate is not allowed by the mode-set, then the next lower bitrate will be used. If no lower bitrates are permitted, then the next higher bitrate will be used.

For outgoing AMR offers, a mode-set can be configured in the preferences page, and it will be honoured just like a mode-set that is received from a remote peer. A remote AMR peer may support only a specific subset of AMR modes, which would need to be configured in the mode-set. The Sipwise C5 supports encoding and decoding all possible AMR modes.

If no mode-set is received nor configured, then all bitrates are permitted.

AMR has two basic payload variants: bandwidth-efficient and octet-aligned. A remote AMR peer may support only one of them, in which case the correct one must be configured in the preferences. The default is bandwidth-efficient. The Sipwise C5 supports sending and receiving both and will honour the request made by a remote AMR peer for one or the other.

Further options that may be required by a remote AMR peer to restrict permissible mode changes are: mode-change-period restricts mode changes to be made only every other packet if set to 2 (the default is 1); mode-change-capability advertises the capability to restrict the modes changes as such without actually restricting them; and mode-change-neighbor restricts mode changes to be made only to neighbouring modes if enabled (the default is disabled).

AMR supports requesting specific encoder modes from the remote peer via Codec Mode Requests (CMR). The Sipwise C5 will honour a CMR received from the remote peer and switch encoder mode accordingly. Then optionally, if no further CMRs are received from the peer, the Sipwise C5 can then try to increase encoder bitrate again to improve audio quality. This can be enabled by setting the mode change interval preference to non-zero. It specifies an interval in milliseconds at which to switch to a higher encoder bitrate if no CMR was received during that time, and if a higher bitrate is available and allowed by the mode-set.

In the opposite direction, the Sipwise C5 can optionally request higher bitrates from the remote peer by sending CMRs out. This can be enabled by setting the CMR interval preference to non-zero. It specifies an interval in milliseconds at which the Sipwise C5 will request a higher bitrate from the remote encoder if a higher bitrate is available and it was not being used during that time.

Another AMR-specific feature is that AMR supports its own comfort noise payload format, called SID (silence indicator) frames, together with explicit support for DTX (discontinuous transmission). When Sipwise C5 receives a SID frame for transcoding, the SID payload is translated to a single noise audio frame according to the noise parameters carried in the SID frame. When this occurs during a DTX event, the opposite receiving side may experience an unexpected transmission gap (DTX). Some RTP receivers may not be able to handle such a transmission gap gracefully. To mitigate such a scenario, an artificial processing delay (akin to a jitter buffer) can be enabled, which allows the Sipwise C5 to produce additional noise audio frames during a SID DTX event. To enable this, the setting rtpproxy.dtx_delay in config.yml must be set to a non-zero value. This value denotes the processing delay in milliseconds, and should be set to just slightly higher than the highest expected ingress jitter. To limit the maximum duration for which extra noise audio should be generated after a SID DTX event, the setting rtpproxy.max_dtx (in seconds) can be set to a non-zero value.

Setting this flag instructs Sipwise C5 to always engage transcoding to the first (preferred) codec indicated by an RTP endpoint, even if another codec is available that is supported by both parties to a call. Enabling this flag can potentially engage the transcoding engine for a call even if none of the other transcoding options are set.

For example: Subscriber A is calling subscriber B. Subscriber A is indicating support for PCMA and G.722. Subscriber B answers the call, rejects PCMA but accepts G.722, and starts sending G.722 to A. Normally Sipwise C5 would not get involved and would let G.722 pass between A and B. But if subscriber B has the always_transcode flag set, Sipwise C5 would now start transcoding the G.722 sent by B into PCMA before forwarding it to A, because PCMA was indicated as the preferred codec by A. Vice versa, PCMA arriving from A would be transcoded into G.722 and then forwarded to B.

Sipwise C5 supports transcoding between DTMF event packets (using the RTP telephone-event type payload) and DTMF tones carried in-band in the audio stream. DTMF transcoding is supported in both directions: transcoding DTMF event packets to DTMF tones, and DTMF tones in an audio stream and transcoding them to DTMF event packets.

Support for DTMF transcoding can be enabled in one of two ways:

Enabling DTMF transcoding for any call requires that all audio passes through the transcoding engine, as well as a DSP for detecting DTMF tones in one direction. This carries an additional performance impact with it, and so DTMF transcoding should only be enabled when really necessary.

Sipwise C5 supports the conversion of SIP INFO messages with application/dtmf-relay payload to DTMF event or PCM DTMF inband tone, depending on whether the destination participant supports the telephone-event RTP payload type or not. DTMF conversion of INFO messages works only in one way direction: DTMF events or PCM DTMF inband tones are not converted back to DTMF INFO messages.

The preference kamailio.proxy.allow_info_method has to be set to yes in config.yml in order to make the DTMF INFO message conversion working.

Enabling DTMF conversion of INFO messages for any call requires that all audio passes through the transcoding engine, as well as a DSP for detecting DTMF tones in one direction. This carries an additional performance impact with it, and so it should only be enabled when really necessary.

RTP supports a special payload format for carrying comfort noise (CN) audio without having to encode it as actual audio. Support for CN is optional and negotiation is normally left up to the endpoints. If CN transcoding is enabled, Sipwise C5 can transcode CN payloads to audio noise and vice versa.

When active and when CN is supported by one endpoint but not the other, any received CN payloads are converted to audio noise and this noise is then inserted into the audio stream. In the reverse direction, Sipwise C5 can optionally detect silence audio frames and then convert these to predefined CN payloads.

To enable silence detection, the setting rtpproxy.silence_detect in config.yml must be set to a non-zero value. This value denotes the silence detection threshold in percent and therefore must be between 0.0 and 100.0. Any audio samples that are lower than the configured threshold will be as silence, and if all audio samples in an audio frame are detected as silence, then that frame will be replaced by a CN frame. To only replace audio frames that contain complete silence with CN frames, a very low but non-zero value can be used here, such as 0.1%.

When a silence audio frame is replaced by a CN frame, the generated CN payload is not based on the audio that is being replaced, but rather taken from the static and predefined setting rtpproxy.cn_payload in config.yml. This is a list of comfort noise parameters according to RFC 3389. The first value in the list is mandatory and denotes the volume of the noise payload in negative dBov (meaning larger values result in quieter audio, with zero being the loudest), while all subsequent values are optional and denote spectral information about the noise. The default is the single value 32, which describes noise with a volume of -32 dBov without any spectral information.

The SMS functionality of Sipwise C5 is disabled by default. In order to enable SMS, change the value of configuration parameter sms.enable to yes in the main configuration file (/etc/ngcp-config/config.yml).

The second step of configuration is related to the SMSC where Sipwise C5 will connect to. Set the following parameters:

Other parameters of the SMSC connection may also need to be changed from the default values, but this is specific to each deployment.

Then, as usual, you have to make the new configuration active:

$ ngcpcfg apply 'Enabled SMS'

There are a few configuration files for the Kannel module, namely:

Finally: see the description of each configuration parameter in the appendix.

Any subscriber registered on Sipwise C5 can apply a call forwarding setting for short messages, referred to as "CFS" (Call Forward - SMS). If the CFS feature is enabled, he can receive the SMs on his mobile phone, for example, instead of retrieving the SMs through the REST API. This is much more convenient for users if they do not have an application on their smartphone or computer that could manage the SMs through the REST API.

In order to enable CFS you have to set the forwarding as usual on the admin web interface, or through the REST API. Navigate to Subscribers → select one → Details → Preferences → Call Forwards and press the Edit button.

Figure 68. Call Forward for SMS

On the LB node you can see a process named "bearerbox". This process has 2 listening ports assigned to it:

The ngcp-service tool also shows the bearerbox process in its summary information:

$ ngcp-service summary
Ok Service                        Managed    Started   Status
-- ------------------------------ ---------- --------- ---------
…
   kannel-bearerbox               managed    by-ha     active
…

The following log files can provide information about the operation of Bearer Box:

On the PRX node you can see a process named "smsbox". This process has a listening port assigned to it: 13002, that is the communication port towards the Bearer Box component running on LB nodes.

The ngcp-service tool also shows the smsbox process in its summary information:

$ ngcp-service summary
Ok Service                        Managed    Started   Status
-- ------------------------------ ---------- --------- ---------
…
   kannel-smsbox                  managed    by-ha     active
…

The following log files can provide information about the operation of SMS Box:

"Start" field reflects DTSTART property of the EVENT. "Start" is mandatory and by default is set to the start of the current day. "Start" value format is datetime.

"Stop" field reflects DTEND property of the EVENT. For the events within recurrence "Stop" will define duration of each iteration.

To specify "Stop" datetime, press button "Set".

Fields to enter DTEND date and time will appear:

To return "Stop" field to the empty value press button "None". Value in the form fields will be preserved, but newly created EVENT will have empty DTEND property.

Other fields in the form are optional. Most of them aren’t visible by default and will be shown if requested by user or required by data into other fields.

RRULE property of the EVENT is a recurrence rule and defines set of the iterations for the EVENT.

To customize recurrence rule for the EVENT select proper repetition unit for the "Repeat" form field. Input field for the recurrence interval will appear left to the frequency select.

According to the selected unit, FREQ property of the EVENT RRULE will be set to one of the: SECONDLY, MINUTELY, HOURLY, DAYLY, WEEKLY, MONTHLY, YEARLY.

To specify end of the EVENT iterations, select "Series stop" value. For the "at date" option will be shown input for the date and time that will define UNTIL property of the EVENT RRULE.

"after" option, respectively, will put entered value to the COUNT property of the EVENT RRULE.

Form fields "By hour", "By week day", "By month", "By month day", "By set position", "By week number", "By year day", "By second" and "By minute" aren’t shown by default. To enter value to any of these fields press according button on the left. Button with field name is grayed off when corresponding EVENT property is empty.

When gray button with field name is pressed, field input control appears on the right. In the same time button with field name becomes orange, indicating that field value will be saved for the EVENT.

Fields with checkboxes controls have auxiliary button "Invert selection". When button "Invert selection" is pressed currently empty checkboxes become selected and currently selected checkboxes become empty.

When form data will be saved, checkboxes values will be saved as coma separated numbers.

BYxxx RRULE properties expand or limit behavior of the FREQ according to the table in the RRULE specification.

Field "By week day" has two variants of the input: checkbox for each week day and text input. Text input can be used, if "By week day" value is more complex than list of week days, separated by coma, for example for FREQ MONTHLY value "2TH,-3FR" in the "By week day" will mean second Thursday from the month start and third Friday from the month end in every month. Such value can’t be presented as checkboxes selection.

Fields "By set position" and "By year day" are text inputs. Value format for these fields is set of the [+/-]NUMBER values, separated by comma.

For the "By year day" minus sign in front of year day number means that this day should be taken by number from the end of the year.

For the "By set position" minus sign in front of the position of the iteration means that the iteration should be taken by number from the end of the generated iterations sequence.

After new event created, event will appear in time set event list. It will have column with rrule text description, buttons to request event edit form or event deletion.

In events list section all events can be redefined uploading ics iCalendar file:

If "Purge existing" option is selected, all existing time set events will be removed before creation of the events from the uploaded file.

To download iCalendar ics file of the time set, press "Download iCalendar".