BroadWorks User Provisioning

BroadWorks users have the option to use the following script to pull subscriber data automatically from the BroadWorks Application Server directly into ClearIP, which uses the BroadWorks open client interface (OCI) API. This enables ClearIP to analyze calls for toll fraud prevention based on the User instead of based only on the calling number.

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.

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.

There must be a a specific Operator selected for this user account. The Operator field cannot be left blank.

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 Broadworks host and credentials as well as the ClearIP credentials:

{
  "broadworks": {
    "host": "host.example.com",
    "port": 2208,
    "level": "SYSTEM_LEVEL",
    "provider": "provider",
    "group": "group",
    "admin": "admin",
    "password": "password1",
    "timeout": 60000
  },
  "clearip": {
    "email": "email",
    "password": "password2"
  }
}

The host should be the BroadWorks AS IP or FQDN. The port normally is 2208. If the access level is SYSTEM_LEVEL, Service Provider and Group are not needed. Admin is the BroadWorks administrator name. Password1 is the password of the BroadWorks administrator. Email is the ClearIP user account email address. Password2 is the ClearIP user account password.

Default Domain

All BroadWorks User IDs must be provisioned in the format of user@domain. If any of the BroadWorks User IDs do not contain the “@” and domain, then a default domain value should be added to the config.json file.

{
  "broadworks": {
    "host": "host.example.com",
    "port": 2208,
    "level": "SYSTEM_LEVEL",
    "provider": "provider",
    "group": "group",
    "admin": "admin",
    "password": "password1",
    "timeout": 60000
    "defaultDomain": "defaultDomain"
  },
  "clearip": {
    "email": "email",
    "password": "password2"
  }
}

For example, if the full Broadworks User ID is 14045266060, but the BroadWorks sends an X-Broadworks-Dnc header with 14045266060@transnexus.com in the user-id parameter, then “transnexus.com” should be entered as the value of the defaultDomain field in the config.json file.

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>
P-Asserted-Identity: <sip:+14045266060@transnexus.com>
X-Broadworks-Dnc: network-address="sip:+14045266060@transnexus.com";user-id="14045266060@transnexus.com"
Call-ID: 123456
CSeq: 1 INVITE
Content-Length: 0

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-broadworks-subscriber-synchronize-linux config.json

The script will connect to the BroadWorks Application Server and ClearIP and push all Service Providers, Groups, and Users from the BroadWorks Application Server directly into ClearIP.

The script will first push all Service Providers into ClearIP. If all Service Providers are uploaded correctly, then the script will push all Groups into ClearIP. Finally, if all Groups are uploaded correctly, then the script will push all Users into ClearIP.

The script will only add new values (Service Providers, Groups, or Users) into ClearIP. If a value is deleted in the BroadWorks Application Server, the script will not delete the corresponding value within ClearIP.

If there are two BroadWorks Application Servers, then the script must be run twice, with two different config files.

Special Characters and Case Sensitivity

ClearIP Service Provider names, Group names, and User IDs must be less than 256 characters long and only contain numbers, letters, spaces, “#”, “@”, “+”, “.”, “,”, “(”, “)”, “-”, or “_”. If any special characters not within this list are found in the BroadWorks Service Provider, Group, or User names, the script will remove the special characters before uploading into ClearIP.

Review Error Logs

Review the logs for any error messages. If any errors are encountered, please refer to the Troubleshooting section below.

Review Uploaded Values in ClearIP

If no errors were 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 Service Providers, Groups, and Users within the BroadWorks Application Server are automatically updated in ClearIP as a cron job can be set up 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 example to run the script every hour. The correct directory must be specified.

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

If there are two BroadWorks Application Servers, two separate tasks must be created, with two different config files.

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-Broadworks-Dnc Header

Once the Service Providers, Groups, and Users are uploaded into ClearIP, the BroadWorks must also be configured to send the user-id parameter in the X-Broadworks-Dnc header in the SIP INVITE.

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

In BroadWorks, set the sendXBroadWorksDNCHeader = true. The default value is false. This parameter controls whether the X-Broadworks-DNC header is allowed to be included in SIP messages for non-DGC connections. This enables calling line ID and connected line ID information to be conveyed between BroadWorks users with different service providers or on different application servers. When set to “true” the X-Broadworks-DNC header is included in all applicable SIP messages.

The following SIP INVITE provides an example of this X-Broadworks-DNC 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-Broadworks-Dnc: network-address="sip:+14045266060@transnexus.com";user-id="+14045266060@transnexus.com"
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.

Troubleshooting

If any errors occur while manually running the script, obtain a copy of the output log and contact TransNexus support. Use this command to write the log contents to a file.

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

Unable to Acquire ClearIP Token

This error occurs if the ClearIP email or password are incorrect or if the server’s public IP address has not been whitelisted for the user account.

Output Log:

observium bin # ./clearip-broadworks-subscriber-synchronize-linux /usr/local/bin/config.json
Validate BroadWorks configuration
Collect data from BroadWorks
Connected to BroadWorks
Request Authentication
Request Login
Request ServiceProviderGetList
Request GroupGetListInSystem
Request UserGetListInSystem
Request Logout
Disconnected from BroadWorks
Synchronizing...
Acquiring ClearIP token...
Unable to acquire ClearIP token.
Error: Error: Error: Request failed with status code 401
    at Object.provisionData (/snapshot/clearip-broadworks-subscriber-synchronize/clearip.js)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
    at async /snapshot/clearip-broadworks-subscriber-synchronize/index.js