NetSapiens User Provisioning

Introduction

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 you need the ability to move NetSapiens Domains from one Reseller to another, you will not be able to use the provisioning script.

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

Setup

1. Select a server

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

2. Create a ClearIP user account for server access

You must create or update a ClearIP user account and whitelist the IP address for the server. This is the only way for the script to access ClearIP and bypass the OTP requirement.

3. 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:

4. 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"
  }
}

5.Test the script

Manually test the script by running the command using the relevant file name and config.json file. For our examples, we are using the Linux script, but you should run the script name that matches your operating system.

./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, then the script will not delete the corresponding value within ClearIP.

6. Review error logs

Review the logs for any error messages. If there are any errors, please obtain a copy of the output log and contact TransNexus support. You can 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.

7. Review uploaded values in ClearIP

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

8. 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, you can setup a cron job on the server to run the script on a regular basis, like every hour.

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. You must specify the correct directory.

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

Once you have added the task, save the crontab file and exit.

You can then review the contents of the crontab file by using the following command:

crontab -l

Verify the new task was correctly saved in the crontab.

9. 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:18001234567@sip.clearip.com SIP/2.0
Via: SIP/2.0/TCP 5.6.7.8:5060;branch=z9hG4bKuofkAzHWHVoP8hH70015F8
Call-ID: 20201118174958065112-49dafb6eb588d21fef6db82761ff121e
Contact:  <sip:dsfsdfsdf@5.6.7.8:5060;transport=tcp>
CSeq: 201 INVITE
From: <sip:14045266060@5.6.7.8>;tag=4Nm0iTKpEC8WAEfL0015F7
Max-Forwards: 19
To:  <sip:18001234567@sip.clearip.com>
Date: Wed, 18 Nov 2020 17:49:58 GMT
Server: NetSapiens SiPBx v41-2-1
X-User-Id: 1000@domain
Allow: ACK,CANCEL,INVITE,MESSAGE,BYE,OPTIONS,INFO,NOTIFY,REFER
Content-Type: application/sdp
Content-Length: 227

10. 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.