This script can be used to automatically pull subscriber data from NetSapiens into ClearIP. This script enables ClearIP to process and analyze calls based on the User instead of the calling number.
Including Reseller
This script can be configured to map subscriber data from NetSapiens into ClearIP in two different ways using the “includeReseller” option.
Include Reseller
When “includeReseller” is true:
| ClearIP | NetSapiens |
|---|---|
| Service Provider Name | reseller |
| Group Name | domain@reseller |
| User Name | user@domain@reseller |
| User ID | user@domain@reseller |
The Application Parameter for all dial translations that send a call to ClearIP needs to be set to:
X-User-ID: <OwnUser>@<OwnDomain>@<OwnTerritory>
If a domain is moved to another reseller in NetSapiens, a new Group and new Users will be created in ClearIP the next time the script runs. Note the following:
- All Users in the old Group will no longer be matched to future calls and effectively abandoned. These abandoned Users and Groups cannot be deleted until all policies that reference them are manually deleted and the retention period of all historical records that reference them has passed.
- New ClearIP policies may need to be created for the new ClearIP Groups and Users that have been moved to a different Service Provider.
Do Not Include Reseller
When “includeReseller” is false:
| ClearIP | NetSapiens |
|---|---|
| Service Provider Name | reseller |
| Group Name | domain |
| User Name | user@domain |
| User ID | user@domain |
The Application Parameter for all dial translations that send a call to ClearIP needs to be set to:
X-User-ID: <OwnUser>@<OwnDomain>
Domains cannot be moved to another reseller in NetSapiens.
Setup
Select a Server
The script can be run on any Linux server. There are no requirements for CPU, disk, or memory. A script is provided for the Linux operating system. 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 One-Time Password (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 from the ClearIP subscriber synchronize binary release.
The downloaded file will include a version in the suffix. Note that in the examples below, X.Y.Z is a placeholder and refers to the actual version downloaded.
Create a config.json File with Login Credentials
When the script is run, it reads its configuration from the JSON file specified by the –config-file argument. The config.json file must include the NetSapiens host and API key as well as the ClearIP credentials, using the following format:
{
"netsapiens": {
"apiKey": "nss_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"host": "core1.example.com",
"includeReseller": true
},
"clearip": {
"email": "email",
"password": "password"
}
}
Modify the configuration parameters as necessary.
Test the Script
Manually test the script by running the command using the file name and config.json file.
Execute a dry run
./clearip-subscriber-synchronize-X.Y.Z --config-file ./config.json --dry-run
The dry run will log data from NetSapiens, but will NOT provision the data to ClearIP. Check the log carefully to be sure the script is working as expected. If there is a problem, an error message in the log file will indicate the problem.
Execute
./clearip-subscriber-synchronize-X.Y.Z --config-file ./config.json
The script will connect to 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-subscriber-synchronize-X.Y.Z --config-file ./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.
- 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-subscriber-synchronize; ./clearip-subscriber-synchronize-X.Y.Z --config-file 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@reseller
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.