NetSapiens User Provisioning

NetSapiens users have the option to use the following script to pull subscriber data automatically from the NetSapiens directly into ClearIP. This enables ClearIP to analyze calls for toll fraud prevention based on the User instead of based only on the calling number.

Domains cannot be moved from one Reseller to another if using this script.

ClearIP does not support moving a Group (domain) from one Service Provider (reseller) to another. If the ability to move NetSapiens Domains from one Reseller to another is needed, the provisioning script cannot be used.

The ClearIP API can be used to provision NetSapiens users into ClearIP, but a different identifier will need to be used than “user@domain” so that the identifier is unique. For example, “user@domain@reseller” can be used as the ClearIP User ID and User Name, “domain@reseller” as the ClearIP Group Name, and “reseller” as the ClearIP Service Provider Name. Alternatively, solely NetSapiens Domains and Users can be provisioned but not Resellers to avoid any conflicts.

Setup

Select a Server

The script can be run on any server. There are no requirements for CPU, disk, or memory. Scripts are provided for Linux, MacOS, and Windows operating systems. The script can also be run on the same server hosting the NetSapiens.

Create a ClearIP User Account for Server Access

A ClearIP user account must be created or updated and the IP address for the server whitelisted. This is the only way for the script to access ClearIP and bypass the OTP requirement.

Download the Script

The script is a compiled binary and must be saved in any directory on the server. The file can be obtained here:

Create a config.json File with Login Credentials

When the script is run, it looks for a config.json file in the same directory as the script. The config.json file must have contents like this example and needs to include the netsapiens host and credentials as well as the ClearIP credentials:

{
  "netsapiens": {
    "host": "core1.example.com",
    "clientId": "client_id",
    "clientSecret": "client_secret",
    "username": "username",
    "password": "password"
  },
  "clearip": {
    "email": "email",
    "password": "password"
  }
}

Test the Script

Manually test the script by running the command using the relevant file name and config.json file. For these examples, the Linux script is being used, but run the script name that matches the operating system in use.

./clearip-netsapiens-subscriber-synchronize-linux config.json

The script will connect to the NetSapiens and ClearIP and push all resellers, domains, and users from the NetSapiens directly into ClearIP.

The script will first push all resellers into the ClearIP Service Providers page. If all resellers are uploaded correctly, then the script will push all domains into the ClearIP Groups page. Finally, if all domains are uploaded correctly, then the script will push all users into the ClearIP Users page. All ClearIP Groups must be assigned to a Service Provider to be valid. This means each domain in the NetSapiens must be assigned to a specific reseller. Similarly, all ClearIP Users must be assigned to a Group.

The script will only add new values (resellers, domains, or users) into ClearIP. If a value is deleted in the NetSapiens, the script will not delete the corresponding value within ClearIP.

Review Error Logs

Review the logs for any error messages. If there are any errors, obtain a copy of the output log and contact TransNexus support. Use this command to write the log contents to a file.

./clearip-netsapiens-subscriber-synchronize-linux config.json > log.txt

Here are examples of conditions that will cause an error:

• There are invalid characters or too many characters in Reseller, Domain, or User names. These names must have fewer than 256 characters. Valid characters include numbers, letters, spaces, “#”, “*”, “+”, “@”, “.”, “,”, “-”, and “_”.
• A NetSapiens Domain exists without a Reseller.
• A NetSapiens User exists without a Domain.
• A NetSapiens Connection exists without a Domain.
• A NetSapiens Domain has been moved to a different Reseller.
• The script is unable to communicate with ClearIP.
• THe ClearIP User Account used by the script did not accept the EULA or set a permanent password.

Review Uploaded Values in ClearIP

If no errors are found, review the ClearIP Service Providers, Groups, and Users pages to verify the values were uploaded correctly.

Setup cron Job to Run the Script Periodically

To ensure newly added resellers, domains, and users within the NetSapiens are automatically updated in ClearIP as well, setup a cron job on the server to run the script on a regular basis, every hour for instance.

To add the cron job, open the cron configuration file by using the following command:

crontab -e

This opens the crontab file using the vi editor. Add a line like this to run the script every hour. The correct directory must be specified.

0 * * * * cd /DIRECTORY/clearip-netsapiens-subscriber-synchronize-linux; ./clearip-netsapiens-subscriber-synchronize-linux config.json

Once the task is added, save the crontab file and exit.

Review the contents of the crontab file by using the following command:

crontab -l

Verify the new task was correctly saved in the crontab.

Send X-User-Id Header

Once the resellers, domains, and users are uploaded into ClearIP, the NetSapiens must also be configured to send an X-User-Id header in the SIP INVITE.

The NetSapiens can be configured to include the User Id of the calling party as an X-header in the SIP INVITE sent to ClearIP. ClearIP will match the User Id in the SIP INVITE to the corresponding User Id in the Users page.

The following SIP INVITE provides an example of this X-User-Id header.

INVITE sip:+18554742536@sip.clearip.com:5060 SIP/2.0
Via: SIP/2.0/TCP sip.clearip.com:5060
From: <sip:+14045266060@transnexus.com:5060>
To: <sip:+18554742536@sip.clearip.com:5060>
X-User-Id: 1000@domain
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0

Send a Test Call

Send a test call to ClearIP and verify in the SIP Messages page that the call is labelled with the correct Service Provider, Group, and User fields.