BroadWorks User Provisioning

Introduction

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

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.

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.

You must have a specific Operator selected for this user account. You cannot leave the Operator field blank.

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 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 your BroadWorks AS IP or FQDN. The port normally is 2208. If the access level is SYSTEM_LEVEL, then 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 4045266060, but the BroadWorks sends an X-Broadworks-Dnc header with 4045266060@defaultdomain.com in the user-id parameter, then “defaultdomain.com” should be entered as the value of the defaultDomain field in the config.json file.

INVITE sip:+16051231234@sip.clearip.com:5060 SIP/2.0
Via: SIP/2.0/TCP 66.208.53.182:5060;branch=z9hG4bK1sansay631211489rdb9183
To:  <sip:+16051231234@sip.clearip.com>
From: <sip:+14045266060@1.1.1.1>;
Call-ID: ers-3352002271-0-1504874654@1.1.1.1
CSeq: 1 INVITE
Contact:  <sip:+14045266060@1.1.1.1:5060>
Supported:
P-Asserted-Identity: <sip:+14045266060@defaultdomain.com;user=phone>
Privacy: none
Allow: ACK,BYE,CANCEL,INFO,INVITE,OPTIONS,PRACK,REFER,NOTIFY
X-Broadworks-Dnc: network-address="sip:+14045266060@defaultdomain.com;user=phone";user-id="4045266060@defaultdomain.com"
Accept: application/media_control+xml,application/sdp,application/x-broadworks-call-center+xml,multipart/mixed
Max-Forwards: 8
Content-Length: 0

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

If there are two BroadWorks Application Servers, then you must run the script 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, then the script will remove the special characters before uploading into ClearIP.

6. Review error logs

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

7. Review uploaded values in ClearIP

If no errors were found, then 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 service providers, groups, and users within the BroadWorks Application Server 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 similar this example to run the script every hour. You must specify the correct directory.

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

If there are two BroadWorks Application Servers, then you must create two separate tasks, with two different config files.

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-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:18001234567@sip.clearip.com:5060 SIP/2.0
Via: SIP/2.0/TCP sip.clearip.com:5060
From: "Alice" <sip:14045266060@5.6.7.8:5060>;tag=123456789
To: "Bob" <sip:18001234567@1.2.3.4:5060>
X-Broadworks-Dnc: network-address="sip:+14045266060@9.9.9.9;user=phone";user-id="9999"
Call-ID: 1-12345@5.6.7.8
CSeq: 1 INVITE
Max-Forwards: 70
Content-Length: 0

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.

Troubleshooting

If any errors occur while manually running the script, 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-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