Press "Enter" to skip to content

Remotely customize and deploy the 3CX Client

dan 0

3CX is a VOIP phone system that is probably the best value in the small business space.

While there are very good opensource and free phone systems, as far as paid systems go, I do not think anything is as easy as 3CX (www.3cx.com). One of the issues I’ve had with it, is having to deploy custom settings for the windows client across the network. They are working on making this easier, but for now it is one of the issues that some other systems do better. This is dealing with over 100 phones. If you have a small office, then you can easily do it manually.

I posted this in the 3cx forums on their site and am putting it here for reference as well.

Below is the forum post.

Everyone has been wanting a way to remotely deploy, customize, and provision the 3CX client for windows and 3CX has been working on it and the expected update to add this feature is near.

However, because the need is there and we have been wanting the same thing, I’ve worked out some steps outlined below along with a batch file plus a powershell script to allow remote deploy, provision, and companywide customization. I’ve tested it in our environment and it works just as describe. We can push out the 3cx client to any and all PC’s, and if the user has ever logged into the machine, they will get their own 3cx configuration along with any company wide customization we want.

The primary manual process in this is creating the 3cxconfig files from the welcome email and placing them in a network share. Once you have these, you can use them to push the configuration out to all the PC’s on the network and add the needed 3cxPhone.xml files for each user.

The first step is getting the user configuration files. There are two ways I know of to obtain them. Send the welcome email, which would require the user then forwarding it to you or changing their email to your email so you can download it from the attachment. Then rename it *username.3cxconfig* with “username” being the users login name.

Another way you can obtain them is run the 3cx client without an account assigned to it. Just open it up, delete any accounts in there. You may need to close it and open the program up again, but while it’s running you should be able to goto the 3CX console > Phones and see “New” 3CX Phone for Windows. It may not show the correct IP (127.0.0.1) but it should show the MAC address of the machine the un-provisioned client is running on. Assign it to an extension you need the config file for. You should see the windows client immediately update and be configured for that extension. Now on the 3cx console > Phones you will see the “Phone for Windows” phone for that extension. Highlight it and select “+Config”. This is the Welcome Email config file. Copy the text and save it to the network share your using as *username.3cxconfig* with “username” being the users login name.

Once you have all the config files in your network share, you can now modify the batch and powershell scripts to point to those locations. Then use your preferred remote deployment method to execute the batch file. Personally I like PDQ Deploy.

This script is to deploy the 3CX Windows Phone client to remote computers
and to copy the users configuration settings along with customized options
directly into the users AppData folder so when they launch 3CX, even for the
first time, they will already have all their settings and company customization.
There are several pre-requisites for this script to work properly and they are below.

1. You must save a copy of the 3cxconfig file sent by the Welcome Email for each user or by
grabbing the config from the 3CX console > Phones > +Config
This is the most time consuming, however 3CX does not offer another way to get these files.

2. Once you have each users config file, you need to name them “username”.3cxconfig where
“username” is the users domain name. Then copy the file to a network share. (NWPATH). *You are going to want to secure this network path, it has the phone credentials in it.

3. This script will only copy the proper 3cx config files to a users AppData folder if both exist.
That means the user must have already logged into the remote pc at some point in the past and
you must have saved the 3CXconfig file from the welcome email or 3CX console to the network path.

4. You may be able to break this step up, however I have most of it as one long task so that it will only
continue if the previous commands were successful.

5. The powershell script is a separate file and is used to modify all users configuration with custom settings
that you want company wide. For example having a company logo, bringing chat notifications to the front, etc.
You do not need to use it if you want to stick with the default 3cx settings.

6. You will need to make your own Company Logo HeaderImage.jpg and place it in the share path (NWPATH) you are using to have it replaced.

7. You must update the script where it says (NWPATH) to point to wherever your network share and files are located.

8. You must update the script where it says (USER) to be the username of the user running or executing the script remotely.

The basic steps of the script are in this order:
1. Kill the 3CX processes running on the remote machine to allow overwriting any current 3cx config files.
2. Goto the C:\users folder.
3. Make a users.txt file in C:\temp contains a list of all the user folders in C:\users.
4. Scan the users.txt file getting all the usernames that have logged into the pc before and assign them as %%A.
5. Check to see if 3CX Windows phone is installed on the pc. If it is not it will stop.
6. Copy the users welcome email 3cxconfig file form the network share to c:\temp.
7. Run the 3cxconfig file. This will generate the 3cxPhone.xml file with the users settings and place it under
the AppData folder for the account that is running the script.

8. Take a 6 second pause for the 3cx windows client to fully launch and generate the 3cxPhone.xml file.

9. Copy newly generated 3CXPhone.xml file from the user account that is running the batch file and place it in the users AppData folder that the config file corresponds with.

10. Kill the 3CXPhone process that is running in the background created by executing the 3cxconfig file.

11. Delete the Welcome Email 3cxconfig file that was copied to c:\temp.

12. Delete the Users.txt file created in C:\temp and delete 3CXPhone.html in script runner user’s folder.

13. Goto c:\temp.

14. Scan the C:\users directory for all users,

15. Check if they have a 3cxconfig file already setup for their user name.

16. If they do, Copy the powershell script to modify the config file for that user.

17. Copy the companyheader logo you want to use for that client.

17. Run the powershell script

18. The powershell script scans the users config file and replaces whatever settings you want with new ones.

Feel free to modify this all you want, I hoping it won’t be useful for much longer considering 3CX is working hard towards allowing management of the Softphone app from within the 3CX console.

 

 
rem This script is to deploy the 3CX Windows Phone client to remote computers
rem and to copy the users configuration settings along with customized options
rem directly into the users AppData folder so when they launch 3CX, even for the
rem first time, they will already have all their settings and company customization.
rem There are several pre-requisites for this script to work properly and they are below.
rem
rem 1. You must save a copy of the 3cxconfig file sent by the Welcome Email for each user.
rem This is the most time consuming, however 3CX does not offer another way to get these files.
rem 2. Once you have each users welcome email, you need to name them "username".3cxconfig where
rem "username" is the users domain name. Then copy the file to a network share. (NWPATH)
rem 3. This script will only copy the proper 3cx config files to a users AppData folder if both exist.
rem That means the user must have already logged into the remote pc at some point in the past and
rem you must have saved the 3cconfig file from the welcome email to the network path.
rem 4. You may be able to break this up, however I have most of it as one long task so that it will only
rem continue if the previous commands were successful. Preventing it from copying files or attempting to
rem do things that are not needed.
rem 5. The powershell script is a separate file and is used to modify all users configuration with custom settings
rem that you want company wide. For example having a company logo, bringing chat notifications to the front, etc.
rem You do not need to use it if you want to stick with the default 3cx settings.
rem 6. You will need to make your own CompanyLogo HeaderImage.jpg and place it in the share path (NWPATH) you are using to have it replaced.
rem 7. You must update the script where it says (NWPATH) to point to wherever your network share and files are located.
rem 8. You must update the script where it says (USER) to be the name of the user running the script.
rem
rem The basic steps of the script are in this order:
rem 1. Kill the 3CX processes running on the remote machine to allow overwriting any current 3cx config files.
rem 2. Goto the C:\users folder.
rem 3. Make a users.txt file in C:\temp containg a list of all the user folders in C:\users.
rem 4. Scan the users.txt file getting all the usernames that have logged into the pc before and assing them as %%A.
rem 5. Check to see if 3CX Windows phone is installed on the pc. If it is not it will stop.
rem 6. Copy the users welcome email 3cxconfig file form the network share to c:\temp. and delete any previous 3CXPhone.xml file in the running user's folder.
rem 7. Run the 3cxconfig file. This will genereate the 3cxPhone.xml file with the users settings and place it under
rem the AppData folder for the account that is running the script.
rem 8. Take a 3 second pause for the 3cx windows client to fully launch and generate the 3cxPhone.xml file.
rem 9. Copy newly generated 3CXPhone.xml file from the user account that is running the batch file and place it in
rem the users AppData folder that the config file corresponds with.
rem 10. Kill the 3CXPhone process that is running in the background created by executing the 3cxconfig file.
rem 11. Delete the Welcome Email 3cxconfig file that was copied to c:\temp.
rem 12. Delete the Users.txt file created in C:\temp and delete 3CXPhone.html in script runner user's folder.
rem 13. Goto c:\temp.
rem 14. Scan the C:\users directory for all users,
rem 15. Check if they have a 3cxconfig file already setup for their user name.
rem 16. If they do, Copy the powershell script to modify the config file for that user.
rem 17. Copy the companyheader logo you want to use for that client.
rem 17. Run the powershell script
rem 18. The powershell script scans the users config file and replacees whatever settings you want with new ones.
rem
rem
rem Feel free to modify this all you want, I hoping it won't be useful for much longer considering 3CX is working hard towards
rem allowing management of the Softphone app from within the 3CX console.
rem

rem Below is the powershell script. Copy it and save it to a text file with the name of 3cxscript.ps1 (not ending in .txt)
rem Make sure to remove all the "rem" comments at the beginning of each line and the additional two spaces. Put the script in the
rem network share you have the other files (NWPATH)

rem (Copy below this line)
rem
rem Set-ExecutionPolicy RemoteSigned
rem $original_file = '3CXPhone.xml'
rem $destination_file = '3CXPhone.xml'
rem (Get-Content $original_file) | Foreach-Object {
rem $_ -replace 'False', 'True' `
rem -replace '', 'C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg' `
rem -replace '3', '1' `
rem -replace '2', '1' `
rem -replace 'False', 'True' `
rem -replace 'False', 'True' `
rem } | Set-Content $destination_file
rem
rem (Copy above this line)
rem

rem If you want to install the 3cx client as well just add the below lines and remove the "rem" tags.
rem
rem cd c:\temp\
rem xcopy /f /i /y "(NWPATH)\3CXPhoneforWindows15.msi" "C:\temp\3CXPhoneforWindows15.msi*"
rem msiexec /i 3CXPhoneforWindows15.msi /quiet
rem
rem

rem Step 1
taskkill /FI "WINDOWTITLE eq 3CX*" /F

rem Step 2
cd C:\users\

rem Step 3
dir /b > C:\temp\users.txt

rem Steps 4-11
for /F %%A in (C:\temp\users.txt) do if exist "C:\ProgramData\3CXPhone for Windows\PhoneApp\" xcopy /f /i /y "(NWPATH)\%%A.3cxconfig" "c:\temp\%%A.3cxconfig*" && cd C:\temp\ && del "C:\users\(USER)\appdata\roaming\3cxphone for windows\3CXPhone.xml.back" && del "C:\users\(USER)\appdata\roaming\3cxphone for windows\3CXPhone.xml" && start %%A.3cxconfig && timeout /t 3 && xcopy /f /i /y "C:\users\(USER)\appdata\roaming\3cxphone for windows\3CXPhone.xml" "C:\Users\%%A\AppData\Roaming\3CXPhone for Windows\3CXPhone.xml*" && taskkill /FI "WINDOWTITLE eq 3CX*" /F && del "C:\temp\%%A.3cxconfig" && timeout /t 3 && del "C:\users\(USER)\appdata\roaming\3cxphone for windows\3CXPhone.xml.back" && del "C:\users\(USER)\appdata\roaming\3cxphone for windows\3CXPhone.xml"

rem Step 12
del "C:\temp\users.txt"

rem Step 13
cd C:\temp

rem Step 14-18
for /d %%B in (C:\Users\*) do if exist "%%B\AppData\Roaming\3CXPhone for Windows\" cd %%B\AppData\Roaming\3CXPhone for Windows && copy /y (NWPATH)\3cxscript.ps1 && copy /y (NWPATH)\HeaderImage.jpeg "C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg" && powershell -ExecutionPolicy ByPass -File .\3cxscript.ps1

Powershell script by itself

Code:
Set-ExecutionPolicy RemoteSigned
$original_file = '3CXPhone.xml'
$destination_file = '3CXPhone.xml'
(Get-Content $original_file) | Foreach-Object {
$_ -replace 'False', 'True' `
-replace '', 'C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg' `
-replace '3', '1' `
-replace '2', '1' `
-replace 'False', 'True' `
-replace 'False', 'True' `
} | Set-Content $destination_file

Here is the powershell script mentioned above.

Set-ExecutionPolicy RemoteSigned
$original_file = '3CXPhone.xml'
$destination_file =  '3CXPhone.xml'
(Get-Content $original_file) | Foreach-Object {
    $_ -replace 'False', 'True' `
       -replace '', 'C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg' `
       -replace '3', '1' `
       -replace '2', '1' `
       -replace 'False', 'True' `
       -replace 'False', 'True' `
    } | Set-Content $destination_file