Documentation

h1. Provisioning guide

Provisioning of Multimedia Service Platform is performed by the NGNPro SOAP/XML provisioning server. To access the server you need a SOAP/XML client, either the web front-end that comes standard with the platform or one developed by the operator using the supplied SOAP/XML schema.

bq. The examples and screenshots presented in this document have been taken using AG Projects developed NGNPro client part of CDRTool application and may differ from the actual deployment of each customer. Access to the hosted version of Multimedia Service Platform also exposes less functionality, some functions are only available to administrator account and not available to resellers.

It is the responsibility of the operator to build a web interface that talks to the SOAP/XML interface. The sample code provided with CDRTool application is merely an example for how to access the API and should not be used in production by customers.

h2. NGNPro Server

NGNPro server software provides a SOAP/XML provisioning interface that allows for the management of accounts along with all their auxiliary settings.

Using NGNPro SOAP/XML interface the Operator may build new front-ends or adapt the existing CRM, provisioning or support systems to the Multimedia Service Platform, making the integration easy and effective. SOAP/XML is an industry standard for which there are implementations available in almost any programming language (like C, Java, PHP and Python) and it can be used by web developers to create customized web portals for the Operator or its resellers without bothering with the complexity of the platform setup and the database schemas sitting behind.

The SOAP/XML provisioning API is described at:

"https://mdns.sipthor.net/ngnpro/wsdl":https://mdns.sipthor.net/ngnpro/wsdl

h3. SOAP/XML API

# SIP domain management (adding, removing and querying domains)

# SIP account management (adding, updating, deleting and getting a SIP account)

# SIP aliases (adding, deleting and getting SIP aliases for a given SIP account)

# Group membership management (granting, revoking or listing group membership)

# Voicemail account (adding, updating, removing or getting a voicemail account)

# Call diversions (setting or getting the diversions for a given user)

# Retrieving call information for a certain user (missed, placed, received calls)

# Retrieving the registered phones one user has (getting the user locations info)

# ENUM management (adding, removing and getting the ENUM mappings)

# LCR management (adding, removing and getting the PSTN routes and gateways)

!NGNPro-Datatree.png!

h2. Encrypted passwords

The platform can be configured for using encrypted or non encrypted passwords for sip accounts. The web passwords are separate and are currently stored as 'plain' text in the database. The web password allows you to login with a sip account to the settings for that sip account.

If the platform is using encrypted passwords you will be not able to retrieve the password as 'plain' text. This results in that passwords will not be shown in the email you get when sending account info to to configured email address. Only the web password will show, which allows you to login and change the sip account password.

The time you'll know the password before it is encrypted, is when provisioning the accounts (add). At this point in time you should send the email/letter to the customers telling them the info they need. From CDRTool they will get an email without password if the send email to email is used from the Identity tab.

Another consequence is that the web interface will never show the password. It can only be changed.

h2. NGNPro Clients

Multimedia Service Platform comes with a fully featured provisioning client, which is part of CDRTool web application. The Operator may also chose to develop his own web portals to interface with Multimedia Service Platform by using the provided SOAP/XML schema.

h3. Python Client

To help the development of a custom client an attachment:wsdl.tar.gz

Usage is simple and described in the WSDL.Proxy class docstring. In addition to what is mentioned there, you need to also specify the auth argument, which is a dictionary like:

  dict(username='myusername', password='mypassword')

The Proxy, will load the WSDL and add the methods from the specified port in the WSDL on the fly to the proxy instance that is created when you instantiate Proxy(). After the creation you can call the port methods directly on the proxy, so no code generation is needed. You can discover the available methods using inspection on the proxy instance as with any other python object. You pass simple data structures (strings, ints, lists, dicts), that are automatically converted to the appropriate SOAP types.

Inside the archive you'll also find a short example of how to use it in ngnpro_test.py

h3. PHP Client

To use this example code you must install SOAP library for PEAR project.

Generate the library with:

<pre><code class="php">

#!/usr/bin/php

<?

require_once('SOAP/WSDL.php');

$wsdl       = new SOAP_WSDL('https://mdns.sipthor.net/ngnpro/wsdl');

print "<?\n";

print $wsdl->generateAllProxies();

print "?>\n";

?></code>

</pre>

You will end up with a file containing all client functions, attached is an example of the generated file for NGNPro version 4.3.5 attachment:ngnpro_soap_lib.php

The script attachment:sip_add_account.php

h3. Server Location

NGNPro is reachable on the following URLs, which were configured during the setup phase of the platform:

|Platform|Protocol|Port|Location|SOAP ports|

|Collocated Multimedia Service Platform|TLS|443|"https://cdr.example.com/ngnpro":https://cdr.example.com/ngnpro|all ports except Voicemail port|

|Collocated Multimedia Service Platform|TLS|443|"https://cdr.example.com/ngnpro/voicemail":https://cdr.example.com/ngnpro/voicemail|Voicemail port|

|Collocated Multimedia Service Platform|TCP|9200|"http://sip.example.com:9200":http://sip.example.com:9200|all ports except Voicemail port|

|Collocated Multimedia Service Platform|TCP|9200|"http://vm.example.com:9200":http://vm.example.com:9200|Voicemail port|

|Collocated SIP Thor Platform|TLS|9200|"https://ngnpro.example.com:9200":https://ngnpro.example.com:9200|All ports|

h3. Test Server

You can test your provisioning client against the live platform hosted by AG Projects.

|Platform|Protocol|Port|Location|SOAP ports|

|Hosted AG Projects platform|TLS|443|"https://mdns.sipthor.net/ngnpro":https://mdns.sipthor.net/ngnpro|All ports|

The credentials for accessing the test server are the same as the login account used for accessing AG Projects support web page.

h3. SOAP/XML Authentication

SOAP/XML requests must contain valid authentication header with credentials in the form of a combination of username, password and impersonate attributes. There are two types of SOAP credentials to access the server:

* Administrator level. The server has an administrator account configured in the server configuration file, /etc/ngnpro/config.ini, that can be used to perform all functions without restrictions. Set the *impersonate* attribute of the SOAP authentication header to a valid customer of the system to perform actions in behalf of that customer.

* Customer level. Access a partition of the data provisioned into the platform. The customers table, managed using the SOAP/XML CustomerPort, is used as a login database for authenticating and authorizing the SOAP/XML requests. First use the administrator level account to add a customer. When the combination of username/password in the SOAP authentication header matches an entry in the customers table, all actions will be performed in behalf of that customer. This means that any record created will inherit the customer id of the customer and any modification will be checked for ownership before being committed. This allows reseller to have limited access to the platform based on rights assigned to them by the system administrator.

For more information about the *Customer* concept read below.

h2. Customer

Customers are entities created in the platform to store names, address, billing and other information. Customers can also have arbitrary attribute/value pairs stored in the properties attribute.

Each customer is assigned, during creation by the server, a unique id and a reseller id.

h3. Record Assignment

The customer id can be used for assignment of SIP domains, ENUM ranges and DNS zones. The assignment is done by setting the customer id attributes of the record in question.

All SIP accounts inherit the customer id from their parent SIP domain. For example a SIP domain that has customer and reseller attributes set cause all SIP accounts created under this domain to share the same customer and reseller too (because the SIP account always belong to a SIP domain). Same concept works for the ENUM numbers (they belong to ENUM ranges) and DNS records (they belong to DNS zones).

Before deleting a customer, make sure that no records belong to his id.

h2. Reseller

The reseller has the role of grouping multiple customers together. The concept is similar to how the users in a Unix system work, where each user has a unique id and a group id. As opposed to the Unix model, a customer can belong to a single reseller. Customers having their id equal to the reseller_id are referred as resellers. Also customers that have the impersonate attribute set to the reseller id have the same right as their reseller.

If a reseller is not specified during the creation of a new customer entry, a new reseller id equal to the customer id will be assigned, in fact creating a new Reseller in the system. Only provisioning requests made with admin rights can add a reseller into the system.

h3. Conventions for resellers

A customer that is a reseller (the customer id is equal to reseller id) is allowed to create other customers and records in the platform if the *resellerActive* attribute of the customer is set to true.

The number of records each reseller is allowed to provision into the platform is controlled by some special properties belonging to the reseller. These special properties are: sip_credit, sip_alias_credit, enum_range_credit, enum_number_credit, dns_zone_credit, email_credit

The same credit convention is valid for customers belonging to a reseller. Each customer may create records within their own credit. The total of all records created by all customers may not exceed the credit of the reseller. The server checks during creation of each record if the quota has not been exceeded.

The following properties controls if the reseller or customer has access to enable access to PSTN for the SIP accounts:

* pstn_access (can create SIP accounts with PSTN prepaid access)

* prepaid_changes (can toggle a SIP account from prepaid to postpaid and vice versa)

On CDRTool, to create an account that has access to the records belonging to a specific customer set the Impersonate field of the CDRTool login account to *customer_id.reseller_id*.

h3. Conventions for the properties

As mentioned before, each customer can have a list of attributed/value pairs attached to them in the properties attribute, this allowing for storage of arbitrary data with each customer. Each attribute has a field called permission. The following rules apply:

* Properties having permission set to admin can be modified only by the administrator

* Properties having permission set to reseller can be modified by the administrator and their reseller

* Properties having other permission can be modified by their customer, their reseller or by the administrator

If the SIP domain of a SIP account belongs to a customer (the customer_id != 0), the pstn_access and prepaid_access properties can be enabled only if the corespondent reseller has these properties set to 1.

h2. Owner

At SIP account, SIP alias and ENUM number level another attribute called owner exists. Owner attribute can be used to assign or group individual records like SIP accounts and ENUM numbers to customers in the customer table. For example one customer can have multiple SIP accounts and ENUM numbers if their owner field are set to his customer id.

h3. SOAP/XML functions

* CustomerPort->addAccount()

* CustomerPort->updateAccount()

* CustomerPort->deleteAccount()

* CustomerPort->getAccount()

* CustomerPort->getCustomers()

* CustomerPort->getResellers()

* CustomerPort->setProperties()

* CustomerPort->getProperties()

Customer attributes:

<pre>

  <complexType name="CustomerAccount">

  −

  <sequence>

  <element name="id" nillable="true" type="xsd:integer"/>

  <element name="reseller" nillable="true" type="xsd:integer"/>

  <element name="impersonate" nillable="true" type="xsd:integer"/>

  <element name="username" nillable="true" type="xsd:string"/>

  <element name="password" nillable="true" type="xsd:string"/>

  <element name="firstName" nillable="true" type="xsd:string"/>

  <element name="lastName" nillable="true" type="xsd:string"/>

  <element name="organization" nillable="true" type="xsd:string"/>

  <element name="vatNumber" nillable="true" type="xsd:string"/>

  <element name="email" nillable="true" type="xsd:string"/>

  <element name="web" nillable="true" type="xsd:string"/>

  <element name="tel" nillable="true" type="xsd:string"/>

  <element name="fax" nillable="true" type="xsd:string"/>

  <element name="mobile" nillable="true" type="xsd:string"/>

  <element name="sip" nillable="true" type="xsd:string"/>

  <element name="enum" nillable="true" type="xsd:string"/>

  <element name="address" nillable="true" type="xsd:string"/>

  <element name="postcode" nillable="true" type="xsd:string"/>

  <element name="city" nillable="true" type="xsd:string"/>

  <element name="state" nillable="true" type="xsd:string"/>

  <element name="country" nillable="true" type="xsd:string"/>

  <element name="timezone" nillable="true" type="xsd:string"/>

  <element name="language" nillable="true" type="xsd:string"/>

  <element name="bankAccount" nillable="true" type="xsd:string"/>

  <element name="billingAddress" nillable="true" type="xsd:string"/>

  <element name="billingEmail" nillable="true" type="xsd:string"/>

  <element name="balance" nillable="true" type="xsd:double"/>

  <element name="credit" nillable="true" type="xsd:double"/>

  <element name="companyCode" nillable="true" type="xsd:string"/>

  <element name="resellerActive" nillable="true" type="xsd:boolean"/>

  <element name="changeDate" nillable="true" type="xsd:string"/>

  <element name="properties" nillable="true" type="ngnpro:CustomerPropertyArray"/>

  </sequence>

  </complexType>

</pre>

h3. Graphical client

@CDRTool->Accounts->Customers@

!ngnpro-customers.png!

Click on the customer id to edit its properties.

h2. DNS Zones

The SIP Proxy is configured to serve domains that must be reachable over the Internet. The SIP devices must support RFC3263 (Locating SIP Services), namely support for DNS SRV lookups for SIP services. Each SIP domain configured in the SIP Proxy must have DNS zone configured on a DNS server responsable for that domain. When using the platform built-in DNS servers and DNS management you must create the proper DNS zones and records for each SIP domain.

To enable the use of an Internet domain for SIP you must provision in the DNS zone the following records:

  example.com.  300 IN  NAPTR   20 0 "s" "SIP+D2U" "" _sip._udp.example.com.

  _sip._udp.example.com. 300  IN  SRV 0 0 5060 sip.example.com.

Replace example.com with your own domain and add an A record pointing sip.example.com. to the IP address of the SIP Proxy.

h3. SOAP/XML functions

* DnsPort->addZone()

* DnsPort->updateZone()

* DnsPort->deleteZone()

* DnsPort->getZone()

* DnsPort->getZones()

* DnsPort->addRecord()

* DnsPort->addFancyRecord()

* DnsPort->updateRecord()

* DnsPort->updateFancyRecord()

* DnsPort->deleteRecord()

* DnsPort->deleteFancyRecord()

* DnsPort->getRecord()

* DnsPort->getFancyRecord()

* DnsPort->getRecords()

* DnsPort->getFancyRecords()

DNZ zone attributes:

<pre>

<complexType name="DnsZone">

−

<sequence>

<element name="name" nillable="false" type="xsd:string"/>

<element name="ttl" nillable="true" type="xsd:nonNegativeInteger"/>

<element name="nameservers" nillable="true" type="ngnpro:StringArray"/>

<element name="email" nillable="true" type="xsd:string"/>

<element name="serial" nillable="true" type="xsd:int"/>

<element name="refresh" nillable="true" type="xsd:int"/>

<element name="retry" nillable="true" type="xsd:int"/>

<element name="expire" nillable="true" type="xsd:int"/>

<element name="minimum" nillable="true" type="xsd:int"/>

<element name="customer" nillable="true" type="xsd:integer"/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

<element name="info" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

When using AG Projects hosted platform you must select and use for DNS delegation the following name servers:

# ns1.dns-hosting.info

# ns2.dns-hosting.info

h3. Graphical client

@CDRTool->Accounts->DNS zones@

!ngnpro-dns-zones.png!

Click on each zone to edit its properties.

!ngnpro-dns-zone.png!

h2. DNS Records

Each DNS zones has one or more records. For every SIP domain served by the platform you must create the following DNS records:

Example for:

* SIP domain: sipdomain.com

* SIP Proxy hostname configured for the platform: sip.example.com

<pre>

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; DNS records specified by RFC 3263 (Locating SIP services) ;

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; SIP communications using UDP transport

sipdomain.com.             IN NAPTR  10 0 "S" "SIP+d2u" "" _sip._udp.sipdomain.com.

_sip._udp.sipdomain.com.   IN SRV    0  0 5060 sip.example.com.

</pre>

h3. SOAP/XML functions

* DnsPort->addRecord()

* DnsPort->updateRecord()

* DnsPort->deleteRecord()

* DnsPort->getRecord()

* DnsPort->getRecords()

DNS record attributes:

<pre>

<complexType name="DnsRecord">

−

<sequence>

<element name="id" nillable="true" type="xsd:integer"/>

<element name="zone" nillable="true" type="xsd:string"/>

<element name="name" nillable="true" type="xsd:string"/>

<element name="type" nillable="true" type="ngnpro:DnsRecordType"/>

<element name="ttl" nillable="true" type="xsd:unsignedInt"/>

<element name="value" nillable="true" type="xsd:string"/>

<element name="priority" nillable="true" type="xsd:unsignedShort"/>

<element name="owner" nillable="true" type="xsd:integer"/>

<element name="customer" nillable="true" type="xsd:integer"/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

DNS record types:

<pre>

<simpleType name="DnsRecordType">

−

<xsd:restriction base="xsd:string">

<xsd:enumeration value="A"/>

<xsd:enumeration value="AAAA"/>

<xsd:enumeration value="CNAME"/>

<xsd:enumeration value="MX"/>

<xsd:enumeration value="NAPTR"/>

<xsd:enumeration value="NS"/>

<xsd:enumeration value="SRV"/>

<xsd:enumeration value="TXT"/>

<xsd:enumeration value="PTR"/>

<xsd:enumeration value="LOC"/>

</xsd:restriction>

</simpleType>

</pre>

h3. Graphical client

@CDRTool->Accounts->DNS records@

!ngnpro-dns-records.png!

Click on each record to edit its attributes.

!ngnpro-dns-record.png!

h2. SIP Domains

Before creating SIP accounts you need to create at least one SIP domain. (e.g. example.com)

h3. SOAP/XML functions

* SipPort->addDomain()

* SipPort->updateDomain()

* SipPort->deleteDomain()

* SipPort->getDomains()

h3. Graphical client

@CDRTool->Accounts->SIP domains@

!ngnpro-sip-domains.png!

h2. SIP Accounts

The provisioning of SIP account is performed using the SOAP/XML functions present in the Sip port described in NGNPro WSDL.

You must add at least one SIP domain before adding a SIP account.

SIP account passwords can be stored in clear text or encrypted formats depending on how you supply the password. NGNPro needs two MD5 checksums (hexdigests) computed based on the (id.username, id.domain, password) tuple. A hexdigest must be a string of length 32, containing only hexadecimal digits. These hexdigests can be computed by the client and given to NGNPro instead of a clear text password, as follows: the password field must be in "digest1:digest2" form, where digest1=MD5("username:domain:password") and digest2=MD5("username@domain:domain:password"). Otherwise, if the password is given in clear text, NGNPro computes these two digests and stores them. If the store_clear_text_passwords configuration option is set to Yes (the default value), the clear text password will be also be stored. If store_clear_text_passwords is set to No, the password will not be stored and it will not be available in the future.

To enable different rights for SIP accounts, they must be part of specific groups.

You can add or remove a SIP account from a group by using Sip.addToGroup() and Sip.removeFromGroup() SOAP methods. The list of groups to which a SIP account belongs can also be set using the `groups' attribute of the SipAccount structure in Sip.addAccount() and Sip.updateAccount() methods. When you're using a group list for modification, all the old groups will be deleted and the new ones will be inserted in place.

To enable PSTN calls to a SIP account, that account must be in the 'free-pstn' group.

If you want to limit the access to PSTN, in the margins of a predefined quota (expressed in the currency used by CDRTool rating engine), the SIP account must have a positive value set for the 'quota' attribute in the SipAccount structure. In this case, the CDRTool quota system blocks the user if the traffic exceedes the predefined quota by adding the user to the 'quota' group. In this case the SIP account can still place free calls.

A SIP account can be administratively blocked (it cannot make any calls and it cannot register thus not receiving calls), if it's part of the 'blocked' group.

If you want a SIP account to make calls marked as anonymous, that SIP account must be placed in the 'anonymous' group.

To mark a SIP account as prepaid, the 'prepaid' attribute of the SipAccount structure must be set to True.

SipAccount.properties attribute can be used to store per-account information in the form of name-value pairs and they can then be used on the client side for its own purposes. Properties do not influence routing decisions. Their meaning depends on the interpretation the client side gives them, for example they can be used from a web-based interface to store settings like the display language or the account type.

Diversion rules routing order:

# Unavailable,

# Unconditional

# Not-online

# Busy

# No-answer

Not-online means there is no registered device for that account, Unavailable means that the subscriber has accept rules in place that forbid the caller at the current time, accept rules can be temporary (valid a a number of minutes after which they'll be discarded) or scheduled (permanent rules based on time of day and day of week).

The last 2 rules are not handled together with the other 3, they are only handled if the call fails.

h3. SOAP/XML functions

* SipPort->addAccount()

* SipPort->updateAccount()

* SipPort->deleteAccount()

* SipPort->getAccount()

* SipPort->getAccounts()

* SipPort->addToGroup()

* SipPort->removeFromGroup()

* SipPort->getGroups()

* SipPort->addPhonebookEntry()

* SipPort->updatePhonebookEntry()

* SipPort->deletePhonebookEntry()

* SipPort->getPhonebookEntries()

* SipPort->setRejectMembers()

* SipPort->getRejectMembers()

* SipPort->setAcceptRules()

* SipPort->getAcceptRules()

* SipPort->setBarringPrefixes()

* SipPort->getBarringPrefixes()

* SipPort->setCallDiversions()

* SipPort->getCallDiversions()

* SipPort->getCalls()

* SipPort->getCallStatistics()

* SipPort->getSipDeviceLocations()

SIP account attributes:

<pre>

<complexType name="SipAccount">

−

<sequence>

<element name="id" nillable="false" type="ngnpro:SipId"/>

<element name="password" nillable="true" type="xsd:string"/>

<element name="firstName" nillable="true" type="xsd:string"/>

<element name="lastName" nillable="true" type="xsd:string"/>

<element name="email" nillable="true" type="xsd:string"/>

<element name="acl" nillable="true" type="ngnpro:SubscriberACLArray"/>

<element name="groups" nillable="true" type="ngnpro:StringArray"/>

<element name="properties" nillable="true" type="ngnpro:PropertyArray"/>

<element name="timezone" nillable="true" type="xsd:string"/>

<element name="rpid" nillable="true" type="xsd:string"/>

<element name="quota" nillable="true" type="xsd:int"/>

<element name="quickdialPrefix" nillable="true" type="xsd:string"/>

<element name="callLimit" nillable="true" type="xsd:int"/>

<element name="prepaid" nillable="true" type="xsd:boolean"/>

<element name="region" nillable="true" type="xsd:string"/>

<element name="timeout" nillable="true" type="xsd:nonNegativeInteger"/>

<element name="owner" nillable="true" type="xsd:integer"/>

<element name="customer" nillable="true" type="xsd:integer"/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

<element name="createDate" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

Meaning of SIP account attributes:

* rpid: caller id presented to the callee when calling to PSTN destinations

* prepaid: if true, subscriber may call within the limit of its prepaid balance, when balance is zero all calls in progress are cut

* properties: list with attribute/value pairs, used to store arbitrary data per subscriber

* quota: if set to a possitive integer, the subscriber may call to the PSTN up to this limit, calls in progress continue, the usage is reset each calendar month

* region: label that matches a region when calling an emergency number, the call is routed to the emergency point defined for that region

* callLimit: maximum amount of concurrent PSTN calls allowed

* acl: a list of allowed IP networks

* groups: group membership for SIP accounts. Available groups and their meaning:

* free-pstn: subscriber may call to PSTN destinations

* blocked: only calls to emergency numbers defind in the SIP Proxy are allowed

* anonymous: hide caller id when calling to the PSTN (using Privacy headers)

* anonymous-reject: reject calls from "anonymous@anonymous.invalid":mailto:anonymous@anonymous.invalid

* quota: subscriber has been blocked because monthy quota has been exceeded, calls to PSTN destinations are denied

* missed-calls: subscriber will be notifie by email about his sessions in the last 24 hours

Reserved groups for internal use (do not change them):

* prepaid, intercept

On updateAccount() operation all attributes must be supplied otherwise any missing attribute will be deleted. First perform a getAccount() operation, update the attributes that need to be changed and finally perform an updateAccount() with the modified object.

h3. Graphical client

@CDRTool->Accounts->SIP accounts@

!ngnpro-sip-accounts.png!

h3. Control panel

!http://wiki.sip2sip.info/attachments/3809/sip2sip-cp-menu.png(http://wiki.sip2sip.info/attachments/3809/sip2sip-cp-menu.png)!

The above menu gives you access to various settings and information related to your SIP account.

h3. Voicemail

This panel can set the way the voicemail messages are delivered.

!http://wiki.sip2sip.info/attachments/3813/sip2sip-cp-voicemail.png(http://wiki.sip2sip.info/attachments/3813/sip2sip-cp-voicemail.png)!

h3. Online devices

This panel displays the list of registered SIP devices.

!sip2sip-cp-devices.png!

h3. Accept calls

This panel control when and from whom calls are accepted.

!http://wiki.sip2sip.info/attachments/3801/sip2sip-cp-accept.png(http://wiki.sip2sip.info/attachments/3801/sip2sip-cp-accept.png)!

h3. Call diversions

This panel controls the call diversions.

!http://wiki.sip2sip.info/attachments/3807/sip2sip-cp-diversions.png(http://wiki.sip2sip.info/attachments/3807/sip2sip-cp-diversions.png)!

Call diversions data type:

<pre>

<complexType name="CallDiversions">

−

<sequence>

−

<!--

                        FUNC - forward unconditionally

                        FNOL - forward if not online

                        FUNV - forward if not available

                        FNOA - forward if no answer

                        FBUS - forward if busy

                        RUNC - redirect unconditionally

                        RNOL - redirect if not online

                        RUNV - redirect if not available

                        RNOA - redirect if no answer

                        RBUS - redirect if busy

            - Forward conditions cause the traffic to be routed and accounted through the SIP Proxy

            - Redirect conditions cause traffic to be made directly between the caller and end destination, 

              bypassing the SIP Proxy

            - Always used FXXX conditions when accounting is desired

-->

<element name="FUNC" nillable="true" type="xsd:string"/>

<element name="FNOL" nillable="true" type="xsd:string"/>

<element name="FUNV" nillable="true" type="xsd:string"/>

<element name="FNOA" nillable="true" type="xsd:string"/>

<element name="FBUS" nillable="true" type="xsd:string"/>

<element name="RUNC" nillable="true" type="xsd:string"/>

<element name="RNOL" nillable="true" type="xsd:string"/>

<element name="RUNV" nillable="true" type="xsd:string"/>

<element name="RNOA" nillable="true" type="xsd:string"/>

<element name="RBUS" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

h3. Aliases

This panel displays the aliases associated with a SIP account.

!http://wiki.sip2sip.info/raw-attachment/wiki/SipSettings/sip2sip-cp-aliases.png(http://wiki.sip2sip.info/raw-attachment/wiki/SipSettings/sip2sip-cp-aliases.png)!

h2. SIP Aliases

Aliases can be used to provide custom SIP addresses that map to exiting SIP accounts.

h3. SOAP/XML functions

* SipPort->addAlias()

* SipPort->updateAlias()

* SipPort->deleteAlias()

* SipPort->getAlias()

* SipPort->getAliasesForAccount()

* SipPort->getAliases()

h3. Graphical client

@CDRTool->Accounts->SIP aliases@

!ngnpro-sip-aliases.png!

h2. Trusted Peers

Trusted peers are identified by their IP addresses and are allowed to transit the platform. Trusted peers are used to define SIP trunks to/from PBXs allowed to connect to the platform. For more information see "SIP trunking section":http://msp-documentation.ag-projects.com/wiki/PeeringGuide#SIPtrunking.

h3. SOAP/XML functions

* SipPort->addTrustedPeer()

* SipPort->deleteTrustedPeer()

* SipPort->getTrustedPeers()

Trusted peer attributes:

<pre>

<complexType name="TrustedPeer">

−

<sequence>

<element name="ip" nillable="false" type="xsd:string"/>

<element name="protocol" nillable="true" type="ngnpro:TrustedPeerProtocol" default="any"/>

<element name="fromPattern" nillable="true" type="xsd:string" default="^sip:.*$"/>

<element name="tag" nillable="true" type="xsd:string"/>

<element name="description" nillable="true" type="xsd:string" default=""/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

h3. Graphical client

@CDRTool->Accounts->Trusted peers@

!ngnpro-trusted-peers.png!

h2. ENUM Ranges

ENUM is used in the routing logic of the SIP Proxy for sessions that use telephone numbers as identifiers. ENUM is a protocol that provides a translation mechanism for E.164 telephone numbers into IP addressing schemes.

An ENUM range is a telephone number prefix that has been allocated to your platform (by your telephone numbers supplier or telecom regulator in your country). For example you are an operator in Holland (contry code 31) and you have been allocated from the local authorities the numbers 31208005100 till 31208005199 (one hundred numbers). The prefix is therefore 312080051. First create an ENUM range using this prefix, then add individual numbers belonging to this range.

An ENUM range is similar with a DNS zones but it contains extra non DNS attributes like the type of numbers allowed to be stored.

h3. SOAP/XML functions

* EnumPort->addRange()

* EnumPort->updateRange()

* EnumPort->deleteRange()

* EnumPort->getRanges()

ENUM range attributes:

<pre>

<complexType name="EnumRange">

−

<sequence>

<element name="id" nillable="false" type="ngnpro:EnumRangeId"/>

<element name="ttl" nillable="true" type="xsd:nonNegativeInteger" default="3600"/>

<element name="minDigits" nillable="true" type="xsd:int"/>

<element name="maxDigits" nillable="true" type="xsd:int"/>

<element name="size" nillable="true" type="xsd:int"/>

<element name="nameservers" nillable="true" type="ngnpro:StringArray"/>

<element name="used" nillable="true" type="xsd:int"/>

<element name="serial" nillable="true" type="xsd:int"/>

<element name="customer" nillable="true" type="xsd:integer"/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

<element name="info" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

h3. Graphical client

@CDRTool->Accounts->ENUM ranges@

!ngnpro-enum-ranges.png!

Click on each range to modify its properties.

!ngnpro-enum-range.png!

h2. ENUM Numbers

ENUM is used in the routing logic of the SIP Proxy for sessions that use telephone numbers as identifiers. For each SIP account in the platform that must be reachable besides the SIP address also by one ore more telephone numbers, you must create the ENUM numbers and add mappings to their corresponding SIP account. Before creating any ENUM number, you must create an ENUM range.

The ENUM NAPTR record management has been developed based on the standards described at "http://www.ag-projects.com/content/view/61/96/":http://www.ag-projects.com/content/view/61/96/

Each ENUM number may have up to 5 NAPTR records as specified in ETSI TS 102 172 V1.2.1 (Minimum requirements for interoperability of ENUM implementations)

h3. SOAP/XML functions

* EnumPort->addNumber()

* EnumPort->updateNumber()

* EnumPort->deleteNumber()

* EnumPort->getNumber()

* EnumPort->getNumbers()

ENUM number attributes:

<pre>

<complexType name="EnumNumber">

−

<sequence>

<element name="id" nillable="false" type="ngnpro:EnumId"/>

<element name="mappings" nillable="true" type="ngnpro:EnumMappingArray"/>

<element name="info" nillable="true" type="xsd:string"/>

<element name="owner" nillable="true" type="xsd:integer"/>

<element name="customer" nillable="true" type="xsd:integer"/>

<element name="reseller" nillable="true" type="xsd:integer"/>

<element name="changeDate" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

</pre>

ENUM mapping attributes:

<pre>

<complexType name="EnumMapping">

−

<sequence>

<element name="id" nillable="true" type="xsd:int"/>

<element name="type" nillable="true" type="xsd:string"/>

<element name="mapto" nillable="true" type="xsd:string"/>

<element name="priority" nillable="true" type="xsd:int"/>

<element name="ttl" nillable="true" type="xsd:int" default="3600"/>

</sequence>

</complexType>

</pre>

The following NAPTR record types ENUM service types are supported:

<pre>

var $NAPTR_services=array(

        "sip"    => array("service"=>"sip",

                              "webname"=>"SIP",

                              "schemas"=>array("sip:","sips:")),

        "mailto" => array("service"=>"mailto",

                              "webname"=>"Email",

                              "schemas"=>array("mailto:")),

        "web:http"   => array("service"=>"web:http",

                              "webname"=>"WEB (http)",

                              "schemas"=>array("http://")),

        "web:https"  => array("service"=>"web:https",

                              "webname"=>"WEB (https)",

                              "schemas"=>array("https://")),

        "x-skype:callto" => array("service"=>"x-skype:callto",

                              "webname"=>"Skype",

                              "schemas"=>array("callto:")),

        "h323"   => array("service"=>"h323",

                              "webname"=>"H323",

                              "schemas"=>array("h323:")),

        "iax"    => array("service"=>"iax",

                              "webname"=>"IAX",

                              "schemas"=>array("iax:")),

        "iax2"   => array("service"=>"iax2",

                              "webname"=>"IAX2",

                              "schemas"=>array("iax2:")),

        "mms"    => array("service"=>"mms",

                              "webname"=>"MMS",

                              "schemas"=>array("tel:","mailto:")),

        "sms"    => array("service"=>"sms",

                              "webname"=>"SMS",

                              "schemas"=>array("tel:","mailto:")),

        "ems"    => array("service"=>"ems",

                              "webname"=>"EMS",

                              "schemas"=>array("tel:","mailto:")),

        "im"     => array("service"=>"im",

                              "webname"=>"IM",

                              "schemas"=>array("im:")),

        "npd:tel"   => array("service"=>"npd+tel",

                              "webname"=>"Portability",

                              "schemas"=>array("tel:")),

        "void:mailto"  => array("service"=>"void:mailto",

                              "webname"=>"VOID(mail)",

                              "schemas"=>array("mailto:")),

        "void:http"  => array("service"=>"void:http",

                              "webname"=>"VOID(http)",

                              "schemas"=>array("http://")),

        "void:https" => array("service"=>"void:https",

                              "webname"=>"VOID(https)",

                              "schemas"=>array("https://")),

        "voice"  => array("service"=>"voice",

                              "webname"=>"Voice",

                              "schemas"=>array("voice:","tel:")),

        "tel"    => array("service"=>"tel",

                              "webname"=>"Tel",

                              "schemas"=>array("tel:")),

        "fax:tel"    => array("service"=>"fax:tel",

                              "webname"=>"Fax",

                              "schemas"=>array("tel:")),

        "ifax:mailto"   => array("service"=>"ifax:mailto",

                              "webname"=>"iFax",

                              "schemas"=>array("mailto:")),

        "pres"   => array("service"=>"pres",

                              "webname"=>"Presence",

                              "schemas"=>array("pres:")),

        "ft:ftp"    => array("service"=>"ft:ftp",

                              "webname"=>"FTP",

                              "schemas"=>array("ftp://")),

        "loc:http"  => array("service"=>"loc:http",

                              "webname"=>"GeoLocation",

                              "schemas"=>array("http://")),

        "key:http"  => array("service"=>"key:http",

                              "webname"=>"Public key",

                              "schemas"=>array("http://")),

        "key:https"  => array("service"=>"key:https",

                              "webname"=>"Public key (HTTPS)",

                              "schemas"=>array("https://"))

        );

</pre>

h3. Graphical client

@CDRTool->Accounts->ENUM numbers@

!ngnpro-enum-numbers.png!

Click on each number to modify its properties.

!ngnpro-enum-number.png!

h2. Voicemail Accounts

The provisioning is performed using the SOAP/XML functions present in the Voicemail port described in NGNPro WSDL.

To add a voicemail account for a SIP account, the Voicemail.addAccount() method must be used. For each newly created account, a mailbox number will be automatically generated by the provisioning to uniquely identify the voicemail account. If you set the mailbox by yourself, please note that the Asterisk configuration might need to be updated, for example if you give shorter voicemailboxes (3, 4 digits), that are not accepted by default.

By default mailboxes are created starting with number 1000000.

You can configure the voicemail server to delete or store the received voicemail messages by setting VoicemailAccount.VoicemailOptions.delete attribute to True or False, respectively.

To forward requests of a SIP account to the Voicemail account, use the '<voice-mailbox>' wildcard as a value for FUNC, FNOL, FUNV, FNOA, FBUS forwarding indicators in the Sip.setCallDiversions() method.

Each SIP account can access its own voicemail messages and settings by dialing the voicemail extension (by default *70) configured in the SIP Proxy in:

<pre>

  /etc/opensips/config/settings.m4

</pre>

<pre>

  # Number to dial to get to voicemail

  define(`VOICEMAIL_NUMBER', `*70')

</pre>

Some devices are using the * key internally. For such devices you may create an alias in the platform (like voicemail or a full number without *).

Voice messages are by default sent by email. If you wish to store the on the voicemail server and listen to them using a telephone device you must enable voicemail storage option for each SIP account using the provisioning API. If the server storage option is enabled, a Message Waiting Indicator (a.k.a MWI) is sent to the devices that subscribed for this event, the devices supporting such feature will provide an indication that voice messages have been stored on the server.

MWI is enabled if the storage of message on server is enabled. MWI is reset by accessing the voicemail box using a SIP phone.

To change the default content of asterisk email notification, you must edit in /etc/asterisk/voicemail.conf and change the following directives:

<pre>

;emailbody=

;emailsubject=

; Change the from, body and/or subject, variables:

;     VM_NAME, VM_DUR, VM_MSGNUM, VM_MAILBOX, VM_CALLERID, VM_CIDNUM,

;     VM_CIDNAME, VM_DATE

and

;serveremail = notification@some_domain.tld

</pre>

An asterisk reload or restart is required:

  sudo asterisk -r reload

h3. SOAP/XML functions

* VoicemailPort->addAccount()

* VoicemailPort->updateAccount()

* VoicemailPort->deleteAccount()

* VoicemailPort->getAccount()

* VoicemailPort->setAnnouncement()

h2. PSTN Routes

A route is a PSTN prefix, one or more carriers can be assigned for routing sessions for it. PSTN prefixes always start with 00 + Country code. (e.g. 0031 is Nederland). An empty prefix will match all possible routes while a longer match takes precedence. The actual number format sent out to the PSTN gateway can be modified using the gateway rules described below.

h3. SOAP/XML functions

* SipPort->addRoutes()

* SipPort->deleteRoutes()

* SipPort->getRoutes()

h3. Graphical client

@CDRTool->Accounts->PSTN routes@

!ngnpro-pstn-routes.png!

h2. PSTN Carriers

A carrier groups one or more gateways together and can be used during the assignment of PSTN routes. You must define at least one carrier for PSTN routing.

h3. SOAP/XML functions

* SipPort->addCarrier()

* SipPort->deleteCarrier()

* SipPort->getCarriers()

h3. Graphical client

@CDRTool->Accounts->PSTN carriers@

!ngnpro-pstn-carriers.png!

h2. PSTN Gateways

You must define at least one gateway for PSTN routing. Before creating any gateway you must create a carrier.

h3. SOAP/XML functions

* SipPort->addGateway()

* SipPort->updateGateway()

* SipPort->deleteGateway()

* SipPort->getGateways()

h3. Graphical client

@CDRTool->Accounts->PSTN gateways@

!ngnpro-pstn-gateways.png!

h2. PSTN Rules

These rules define the format of the request URI sent to the remote gateway. Rules can be used to strip and prepend digits depending on various conditions.

h3. SOAP/XML functions

* SipPort->addGatewayRule()

* SipPort->updateGatewayRule()

* SipPort->deleteGatewayRule()

* SipPort->getGatewayRules()

h3. Graphical client

@CDRTool->Accounts->PSTN rules@

!ngnpro-pstn-rules.png!

Click on rule to edit its properties.

!ngnpro-pstn-rule.png!

h2. Emergency Numbers

Emergency calls refer to dialing short numbers usually associated with emergency services like police or fire-brigade (e.g. 112 or 911). When a SIP session is setup to a short number designated as emergency (in the SIP Proxy configuration), a secondary database lookup is performed in the proxy database in the emergency_mapping table. Based on the *region* attribute provisioned with each SIP account, the final destination number for the emergency service in the region of the account is looked up.

1. Define the emergency numbers in the /etc/opensips/config/settings.m4

<pre>

  # Emergency numbers

  define(`EMERGENCY_NR1', `112')

  define(`EMERGENCY_NR2', `911')

  define(`EMERGENCY_NRS', `2')

</pre>

2. Add the local access number for each region to emergency_mapping table, the table has the following structure:

  |*Field*|*Type*|

  |id|int(10) unsigned|

  |username|varchar(64)|

  |domain|varchar(64)|

  |region|varchar(32)|

  |target|varchar(128)|

  |change_date|timestamp|

  Example: 

<pre>

+----------+-------------+-----------+-------------------------------+---------------------+

| username | domain      | region    | target                        | change_date         |      

+----------+-------------+-----------+-------------------------------+---------------------+

| 112      | example.com | 010       | sip:0031141217112@example.com | 2006-05-09 14:33:18 | 

| 112      | example.com | 0111      | sip:0031141219112@example.com | 2006-05-09 14:33:18 | 

| 112      | example.com | 0113      | sip:0031141219112@example.com | 2006-05-09 14:33:18 | 

| 112      | example.com | 0114      | sip:0031141219112@example.com | 2006-05-09 14:33:18 | 

| 112      | example.com | 0115      | sip:0031141219112@example.com | 2006-05-09 14:33:18 | 

+----------+-------------+-----------+-------------------------------+---------------------+

</pre>

3. Set the *region* attribute for each SIP account using Sip->updateAccount() to match the region column in emergency_mapping table.

h2. Email Notifications

h3. Quota exceeded

This notification is sent out to the email address associated with SIP accounts that have the *quota* attribute set to a positive value, when the monthly quota has been exceeded. The email is generated by a CDRTool cron job task from the script:

  /var/www/CDRTool/scripts/OpenSIPS/quotaCheck.php

To change the email headers or the body of the notification message you must insert/update a row in cdrtool.settings mysql table. See for an example:

  /var/www/CDRTool/setup/mysql/custom_notifications.mysql 

h3. Voicemail

The notification that contains also the actual voice message as a WAV attachment is sent out by the Asterisk voicemail server. To change the email headers or body you must change the configuration file:

  /etc/asterisk/voicemail.conf

This notification cannot be enabled/disabled per user, it is a global platform setting.

h3. Last sessions

An email with last received sessions in the previous 24 hours is sent out by a CDRTool cronjob script:

  /var/www/CDRTool/scripts/OpenSIPS/notifyLastSessions.php

The From header of the email notification can be modified by changing the following setting from /etc/cdrtool/global.inc:

  $CDRTool['provider']['fromEmail'] ="support@ag-projects.com";

The notification is sent only if the SIP account belongs to the *missed-calls* group.