Guide: How to remotely customize,provision and deploy the 3CX Client

Discussion in 'Windows' started by dan_tx, Feb 7, 2017.

Thread Status:
Not open for further replies.
  1. dan_tx

    Joined:
    Nov 3, 2016
    Messages:
    94
    Likes Received:
    24
    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.

    The code is in the next post, there is a 10k character limit to posts.
     
    Fabio Colbrelli likes this.
  2. dan_tx

    Joined:
    Nov 3, 2016
    Messages:
    94
    Likes Received:
    24
    Code:
    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 '<IsCustomImageSet>False</IsCustomImageSet>', '<IsCustomImageSet>True</IsCustomImageSet>' `
    rem         -replace '<CustomImagePath></CustomImagePath>', '<CustomImagePath>C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg</CustomImagePath>' `
    rem         -replace '<ApplicationTheme>3</ApplicationTheme>', '<ApplicationTheme>1</ApplicationTheme>' `
    rem         -replace '<ApplicationTheme>2</ApplicationTheme>', '<ApplicationTheme>1</ApplicationTheme>' `
    rem         -replace '<StealFocusOnIncomingCall>False</StealFocusOnIncomingCall>', '<StealFocusOnIncomingCall>True</StealFocusOnIncomingCall>' `
    rem         -replace '<AutomaticallyOpenChatWindow>False</AutomaticallyOpenChatWindow>', '<AutomaticallyOpenChatWindow>True</AutomaticallyOpenChatWindow>' `
    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 '<IsCustomImageSet>False</IsCustomImageSet>', '<IsCustomImageSet>True</IsCustomImageSet>' `
           -replace '<CustomImagePath></CustomImagePath>', '<CustomImagePath>C:\ProgramData\3CXPhone for Windows\PhoneApp\HeaderImage.jpeg</CustomImagePath>' `
           -replace '<ApplicationTheme>3</ApplicationTheme>', '<ApplicationTheme>1</ApplicationTheme>' `
           -replace '<ApplicationTheme>2</ApplicationTheme>', '<ApplicationTheme>1</ApplicationTheme>' `
           -replace '<StealFocusOnIncomingCall>False</StealFocusOnIncomingCall>', '<StealFocusOnIncomingCall>True</StealFocusOnIncomingCall>' `
           -replace '<AutomaticallyOpenChatWindow>False</AutomaticallyOpenChatWindow>', '<AutomaticallyOpenChatWindow>True</AutomaticallyOpenChatWindow>' `
        } | Set-Content $destination_file
    
    
    
     
    #2 dan_tx, Feb 7, 2017
    Last edited: Feb 7, 2017
    Fabio Colbrelli likes this.
  3. livn46

    Joined:
    Oct 24, 2014
    Messages:
    78
    Likes Received:
    1
    Looks great. It looks like this is for v15, do you know if it would work for v14?
     
    Stop hovering to collapse... Click to collapse... Hover to expand... Click to expand...
  4. dan_tx

    Joined:
    Nov 3, 2016
    Messages:
    94
    Likes Received:
    24
    I've never used 14, so couldn't say. Unless they have changed how they use 3cxconfig files to provision the windows softphone, I would think it would work just the same.
     
  5. Lewis Burgess

    Joined:
    Jan 6, 2017
    Messages:
    25
    Likes Received:
    8
    Great work...

    This could be improved massively by grabbing the provisioning files by way of querying the database for each user's file.

    The table is dnprop. The filename (generated on the fly it seems) is essentially a timestamp with the user's extension on the end, just before '.xml'. As long as the person's name is input correctly, it should be possible to relatively accurately match to the right person.

    I am creating a Powershell script which provisions the user in 3CX via the API and then put their extension number in to the Active Directory. By having their extension in AD, comparing that with the dnprop database to grab the right provisioning file for them, download it and then use something very much like the above to push them out to users.
     
  6. 3CXusername

    3CXusername New Member

    Joined:
    Jul 31, 2014
    Messages:
    183
    Likes Received:
    16
    I was going to make time next week to do something very similar pulling from DB. If you have something working before hand please let us know.

    thanks
     
    Stop hovering to collapse... Click to collapse... Hover to expand... Click to expand...
    Fabio Colbrelli likes this.
Thread Status:
Not open for further replies.